Skip to content

Class GraphicsDevice

Namespace: Apogee.Graphics
Assembly: Apogee.Graphics.dll

The logical device of one graphics API and everything created with it. The renderer talks to this class and the abstract classes it hands out (buffers, images, pipelines, a command recorder, a swapchain and frame loop); Apogee.Graphics.Vulkan has the Vulkan implementation, and a Metal one follows. The engine's baseline is the same on every API: dynamic rendering, explicit barriers, buffer device addresses and bindless textures; a GPU without them is rejected with the reason.

public abstract class GraphicsDevice : IDisposable

Inheritance

object ← GraphicsDevice

Derived

MetalDevice, VulkanDevice

Implements

IDisposable

Inherited Members

object.Equals(object?), object.Equals(object?, object?), object.GetHashCode(), object.GetType(), object.MemberwiseClone(), object.ReferenceEquals(object?, object?), object.ToString()

Properties

Backend

public abstract GraphicsBackend Backend { get; }

Property Value

GraphicsBackend

Bindless

The set of textures and samplers every pipeline sees, by index.

public BindlessHeap Bindless { get; protected set; }

Property Value

BindlessHeap

DefaultBackend

The API used when nothing is asked for: APOGEE_GRAPHICS, else the platform's (Metal on macOS, Vulkan elsewhere).

public static GraphicsBackend DefaultBackend { get; }

Property Value

GraphicsBackend

Immediate

Records, submits and waits: for loading and tools.

public ImmediateContext Immediate { get; protected set; }

Property Value

ImmediateContext

Kind

public abstract GpuKind Kind { get; }

Property Value

GpuKind

MaxSamplerAnisotropy

public abstract float MaxSamplerAnisotropy { get; }

Property Value

float

MinUniformBufferOffsetAlignment

public abstract ulong MinUniformBufferOffsetAlignment { get; }

Property Value

ulong

Name

public abstract string Name { get; }

Property Value

string

ShaderBackend

The kind of shader code this device runs: pass it to .

public abstract ShaderBackend ShaderBackend { get; }

Property Value

ShaderBackend

SupportsAnisotropy

public abstract bool SupportsAnisotropy { get; }

Property Value

bool

SupportsAstc

ASTC LDR textures can be sampled (mobile and Apple GPUs).

public abstract bool SupportsAstc { get; }

Property Value

bool

SupportsBc

BC1-7 textures can be sampled (desktop GPUs); otherwise transcode Basis textures to ASTC or RGBA8.

public abstract bool SupportsBc { get; }

Property Value

bool

SupportsDrawIndirectCount

works: the GPU decides how many draws to make (Vulkan's optional drawIndirectCount). Metal has no such draw; use with a maximum count instead.

public abstract bool SupportsDrawIndirectCount { get; }

Property Value

bool

SupportsSamplerFilterMinMax

Samplers can return the minimum or maximum of their footprint (): a Hi-Z pyramid can be built with a single sample per texel. Metal has none; a shader takes the four texels itself.

public abstract bool SupportsSamplerFilterMinMax { get; }

Property Value

bool

SupportsTimestamps

The queue writes timestamps (all of graphics and compute can).

public abstract bool SupportsTimestamps { get; }

Property Value

bool

TimestampPeriod

Nanoseconds per timestamp tick, for GPU timings.

public abstract float TimestampPeriod { get; }

Property Value

float

ValidationErrorCount

How many warnings and errors the API's validation layer has reported; tests fail on any.

public abstract int ValidationErrorCount { get; }

Property Value

int

Methods

Create(GraphicsDeviceOptions?)

Creates the device on the best usable GPU. Throws with every GPU's reason when none qualifies.

public static GraphicsDevice Create(GraphicsDeviceOptions? options = null)

Parameters

options GraphicsDeviceOptions?

Returns

GraphicsDevice

CreateBuffer(ulong, BufferUsage, MemoryKind, string?)

public abstract GpuBuffer CreateBuffer(ulong size, BufferUsage usage, MemoryKind kind = MemoryKind.DeviceLocal, string? name = null)

Parameters

size ulong

usage BufferUsage

kind MemoryKind

name string?

Returns

GpuBuffer

CreateBuffer(ReadOnlySpan<byte>, BufferUsage, string?)

Creates a device-local buffer holding data.

public GpuBuffer CreateBuffer(ReadOnlySpan<byte> data, BufferUsage usage, string? name = null)

Parameters

data ReadOnlySpan<byte>

usage BufferUsage

name string?

Returns

GpuBuffer

CreateComputePipeline(in ShaderCode, string?)

public abstract Pipeline CreateComputePipeline(in ShaderCode shader, string? name = null)

Parameters

shader ShaderCode

name string?

Returns

Pipeline

CreateFrameLoop(Swapchain?, int, int)

The loop that records and submits frames, to swapchain or headless.

public abstract FrameLoop CreateFrameLoop(Swapchain? swapchain = null, int framesInFlight = 2, int arenaBytes = 4194304)

Parameters

swapchain Swapchain?

framesInFlight int

arenaBytes int

Returns

FrameLoop

CreateGraphicsPipeline(GraphicsPipelineDescription, string?)

public abstract Pipeline CreateGraphicsPipeline(GraphicsPipelineDescription description, string? name = null)

Parameters

description GraphicsPipelineDescription

name string?

Returns

Pipeline

CreateImage(in ImageDescription, string?)

public abstract GpuImage CreateImage(in ImageDescription description, string? name = null)

Parameters

description ImageDescription

name string?

Returns

GpuImage

CreateSampler(in SamplerDescription, string?)

public abstract GpuSampler CreateSampler(in SamplerDescription description, string? name = null)

Parameters

description SamplerDescription

name string?

Returns

GpuSampler

CreateSwapchain(bool)

A swapchain for the window the device was created for ().

public abstract Swapchain CreateSwapchain(bool vsync = true)

Parameters

vsync bool

Returns

Swapchain

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public abstract void Dispose()

EnumerateDevices(GraphicsDeviceOptions?)

Lists the GPUs the API reports, with whether each meets the baseline.

public static GpuInfo[] EnumerateDevices(GraphicsDeviceOptions? options = null)

Parameters

options GraphicsDeviceOptions?

Returns

GpuInfo[]

ReadBuffer(GpuBuffer, ulong, int)

Copies a buffer's bytes back to the CPU (through a readback buffer when it is on the GPU) and waits.

public byte[] ReadBuffer(GpuBuffer source, ulong offset, int length)

Parameters

source GpuBuffer

offset ulong

length int

Returns

byte[]

ReadImage(GpuImage, ImageState, uint, uint)

Copies one mip level of one layer of an image, which is in state, back to the CPU as packed texels, and leaves it in that state.

public byte[] ReadImage(GpuImage source, ImageState state, uint mipLevel = 0, uint layer = 0)

Parameters

source GpuImage

state ImageState

mipLevel uint

layer uint

Returns

byte[]

RequiredWindowOptions(GraphicsBackend?)

The flag a window needs to present to a device of this API (a window must be created for the API it will be drawn with).

public static WindowOptions RequiredWindowOptions(GraphicsBackend? backend = null)

Parameters

backend GraphicsBackend?

Returns

WindowOptions

TakeValidationErrors()

Takes the validation messages reported so far.

public abstract string[] TakeValidationErrors()

Returns

string[]

TryCreate(GraphicsDeviceOptions?, out GraphicsDevice?, out string?)

Like , for a machine that may have no usable GPU or driver: says why instead of throwing.

public static bool TryCreate(GraphicsDeviceOptions? options, out GraphicsDevice? device, out string? error)

Parameters

options GraphicsDeviceOptions?

device GraphicsDevice?

error string?

Returns

bool

UploadBuffer(GpuBuffer, ReadOnlySpan<byte>, ulong)

Copies data into a buffer (through a staging buffer when the buffer is on the GPU) and waits for it. For loading, not for every frame.

public void UploadBuffer(GpuBuffer destination, ReadOnlySpan<byte> data, ulong offset = 0)

Parameters

destination GpuBuffer

data ReadOnlySpan<byte>

offset ulong

UploadImage(GpuImage, ReadOnlySpan<byte>, ReadOnlySpan<ImageRegion>, ImageState)

Fills subresources of a fresh image from packed texel data and leaves it in finalState. The image must not have been used yet (its layout is undefined).

public void UploadImage(GpuImage destination, ReadOnlySpan<byte> data, ReadOnlySpan<ImageRegion> regions, ImageState finalState)

Parameters

destination GpuImage

data ReadOnlySpan<byte>

regions ReadOnlySpan<ImageRegion>

finalState ImageState

WaitIdle()

public abstract void WaitIdle()