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¶
Derived¶
Implements¶
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¶
Bindless¶
The set of textures and samplers every pipeline sees, by index.
public BindlessHeap Bindless { get; protected set; }
Property Value¶
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¶
Immediate¶
Records, submits and waits: for loading and tools.
public ImmediateContext Immediate { get; protected set; }
Property Value¶
Kind¶
public abstract GpuKind Kind { get; }
Property Value¶
MaxSamplerAnisotropy¶
public abstract float MaxSamplerAnisotropy { get; }
Property Value¶
MinUniformBufferOffsetAlignment¶
public abstract ulong MinUniformBufferOffsetAlignment { get; }
Property Value¶
Name¶
public abstract string Name { get; }
Property Value¶
ShaderBackend¶
The kind of shader code this device runs: pass it to
public abstract ShaderBackend ShaderBackend { get; }
Property Value¶
SupportsAnisotropy¶
public abstract bool SupportsAnisotropy { get; }
Property Value¶
SupportsAstc¶
ASTC LDR textures can be sampled (mobile and Apple GPUs).
public abstract bool SupportsAstc { get; }
Property Value¶
SupportsBc¶
BC1-7 textures can be sampled (desktop GPUs); otherwise transcode Basis textures to ASTC or RGBA8.
public abstract bool SupportsBc { get; }
Property Value¶
SupportsDrawIndirectCount¶
drawIndirectCount). Metal has no such draw; use
public abstract bool SupportsDrawIndirectCount { get; }
Property Value¶
SupportsSamplerFilterMinMax¶
Samplers can return the minimum or maximum of their footprint (
public abstract bool SupportsSamplerFilterMinMax { get; }
Property Value¶
SupportsTimestamps¶
The queue writes timestamps (all of graphics and compute can).
public abstract bool SupportsTimestamps { get; }
Property Value¶
TimestampPeriod¶
Nanoseconds per timestamp tick, for GPU timings.
public abstract float TimestampPeriod { get; }
Property Value¶
ValidationErrorCount¶
How many warnings and errors the API's validation layer has reported; tests fail on any.
public abstract int ValidationErrorCount { get; }
Property Value¶
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¶
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¶
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¶
CreateComputePipeline(in ShaderCode, string?)¶
public abstract Pipeline CreateComputePipeline(in ShaderCode shader, string? name = null)
Parameters¶
shader ShaderCode
name string?
Returns¶
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¶
CreateGraphicsPipeline(GraphicsPipelineDescription, string?)¶
public abstract Pipeline CreateGraphicsPipeline(GraphicsPipelineDescription description, string? name = null)
Parameters¶
description GraphicsPipelineDescription
name string?
Returns¶
CreateImage(in ImageDescription, string?)¶
public abstract GpuImage CreateImage(in ImageDescription description, string? name = null)
Parameters¶
description ImageDescription
name string?
Returns¶
CreateSampler(in SamplerDescription, string?)¶
public abstract GpuSampler CreateSampler(in SamplerDescription description, string? name = null)
Parameters¶
description SamplerDescription
name string?
Returns¶
CreateSwapchain(bool)¶
A swapchain for the window the device was created for (
public abstract Swapchain CreateSwapchain(bool vsync = true)
Parameters¶
vsync bool
Returns¶
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¶
TakeValidationErrors()¶
Takes the validation messages reported so far.
public abstract string[] TakeValidationErrors()
Returns¶
string[]
TryCreate(GraphicsDeviceOptions?, out GraphicsDevice?, out string?)¶
Like
public static bool TryCreate(GraphicsDeviceOptions? options, out GraphicsDevice? device, out string? error)
Parameters¶
options GraphicsDeviceOptions?
device GraphicsDevice?
error string?
Returns¶
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()