GraphicsAPI reference
Interface IGraphicsDevice
Namespace: MicroEngine.Graphics.Devices
Assembly: MicroEngine.Graphics.dll
Guide: The graphics device
The single graphics device contract for every tier. Tiers differ only in Capabilities; a request outside them throws GraphicsCapabilityException at creation or recording time.
Ordering rule: command lists execute in [Submit](/docs/api/microengine.graphics.devices.igraphicsdevice/#MicroEngine_Graphics_Devices_IGraphicsDevice_Submit_MicroEngine_Graphics_Devices_CommandList_) order, and within a list in recording order (updates included); [ReadPixels](/docs/api/microengine.graphics.devices.igraphicsdevice/#MicroEngine_Graphics_Devices_IGraphicsDevice_ReadPixels_MicroEngine_Graphics_Devices_RenderTarget_MicroEngine_Graphics_Devices_RectI_) observes every list submitted before it.
Threading: one thread (the render thread) creates, records, submits and presents.
public interface IGraphicsDevice : IDisposableImplements
Properties
Capabilities
Declared capabilities.
GraphicsCapabilities Capabilities { get; }Property Value
Counters
Deterministic counts of the work submitted to this device since it was created (draw calls, passes, uploads, live resources). Every device built on GraphicsDeviceBase counts; a device that does not reports zeros.
GraphicsCounters Counters { get; }Property Value
Methods
BeginCommands()
Starts an empty command list for this device.
CommandList BeginCommands()Returns
CreateBuffer(in BufferDescription)
Creates a buffer (every tier).
GpuBuffer CreateBuffer(in BufferDescription description)Parameters
description BufferDescription
Returns
CreatePipeline(PipelineDescription)
Creates a custom pipeline; requires Shaders, and DepthBuffer for depth.
Pipeline CreatePipeline(PipelineDescription description)Parameters
description PipelineDescription
Returns
CreateRenderTarget(in RenderTargetDescription)
Creates an offscreen target; requires RenderTargets. Contents are undefined until a pass clears or draws.
RenderTarget CreateRenderTarget(in RenderTargetDescription description)Parameters
description RenderTargetDescription
Returns
CreateShader(in ShaderDescription)
Creates a custom shader; requires Shaders and a declared format. Invalid bytecode fails here or at CreatePipeline, never at draw.
Shader CreateShader(in ShaderDescription description)Parameters
description ShaderDescription
Returns
CreateTexture(in TextureDescription, ReadOnlySpan<byte>)
Creates a sampled texture, optionally with initial data (exactly ByteCount bytes of level 0, or empty).
Texture CreateTexture(in TextureDescription description, ReadOnlySpan<byte> initialData = default)Parameters
description TextureDescription
initialData ReadOnlySpan<byte>
Returns
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.
Pipeline GetBuiltInPipeline(BuiltInPipeline kind, BlendState blend, TextureFormat colorFormat, TextureFormat? depthFormat = null)Parameters
kind BuiltInPipeline
blend BlendState
colorFormat TextureFormat
depthFormat TextureFormat?
Returns
GetSampler(in SamplerDescription)
Returns the cached sampler for a description.
Sampler GetSampler(in SamplerDescription description)Parameters
description SamplerDescription
Returns
Present()
Presents the acquired surface target (no-op when none was acquired) and expires it.
void Present()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.
ReadbackRequest ReadPixels(RenderTarget target, RectI region)Parameters
target RenderTarget
region RectI
Returns
Submit(CommandList)
Executes a finished list (no open pass) after every list submitted before it. A list is submitted once.
void Submit(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.
bool TryAcquireSurfaceTarget(out RenderTarget? target)Parameters
target RenderTarget?
Returns
DeviceLost
Optional: raised only by backends that can detect loss (SDL_GPU never raises it); resources are marked IsLost.
event Action<DeviceLostReason>? DeviceLost