Class CompiledShader

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

A shader compiled ahead of time from one HLSL source into every format a tier-1 device may accept (DXIL for Direct3D 12, SPIR-V for Vulkan, MSL for Metal), with the resource counts reflection found. It is what microengine shaders writes (one .shader file per HLSL file) and what a game ships: nothing compiles at run time. DescriptionFor picks the format a device should be given; a device without custom shaders gets the typed GraphicsCapabilityException, as for any undeclared capability.

C#

public sealed class CompiledShader

Inheritance

object ← CompiledShader

Remarks

The file is UTF-8 JSON: {“format”:“microengine-shader”,“version”:1,“stage”:“vertex”|“fragment”,“source”:…, “resources”:{“samplers”:n,“uniformBuffers”:n},“code”:{“dxil”|“spirv”|“msl”:{“entry”:…,“base64”:…}}}. Binding rules are SDL_GPU’s (see ShaderResources).

Constructors

CompiledShader(ShaderStage, ShaderResources, IReadOnlyDictionary<ShaderFormat, ShaderCode>, string?)

Creates a compiled shader from its code in one or more formats.

C#

public CompiledShader(ShaderStage stage, ShaderResources resources, IReadOnlyDictionary<ShaderFormat, ShaderCode> code, string? source = null)

Parameters

stage ShaderStage

Stage.

resources ShaderResources

Reflected resource counts (the same for every format).

code IReadOnlyDictionary<ShaderFormat, ShaderCode>

Code by format; each key is exactly one format.

source string?

The source file it was compiled from, for diagnostics.

Exceptions

ArgumentException

No code, a key that is not exactly one format, or an empty entry point or code.

Fields

FileExtension

The file extension of a compiled shader (“sprite.frag.hlsl” compiles to “sprite.frag.shader”).

C#

public const string FileExtension = ".shader"

Field Value

string

FormatVersion

The file format version this assembly reads and writes.

C#

public const int FormatVersion = 1

Field Value

int

Properties

Formats

The formats this shader has code for.

C#

public ShaderFormat Formats { get; }

Property Value

ShaderFormat

Resources

Reflected resource counts.

C#

public ShaderResources Resources { get; }

Property Value

ShaderResources

Source

The source file it was compiled from, or null.

C#

public string? Source { get; }

Property Value

string?

Stage

Stage.

C#

public ShaderStage Stage { get; }

Property Value

ShaderStage

Methods

Create(IGraphicsDevice)

Creates the shader on device in the format DescriptionFor picks.

C#

public Shader Create(IGraphicsDevice device)

Parameters

device IGraphicsDevice

Returns

Shader

Exceptions

GraphicsCapabilityException

See DescriptionFor.

DescriptionFor(GraphicsCapabilities)

The description to give a device with capabilities: the format its API runs natively (DXIL on Direct3D 12, MSL on Metal, SPIR-V on Vulkan), otherwise the first format both sides have.

C#

public ShaderDescription DescriptionFor(GraphicsCapabilities capabilities)

Parameters

capabilities GraphicsCapabilities

Returns

ShaderDescription

Exceptions

GraphicsCapabilityException

The device declares no custom shaders (Shaders), or none of the formats this shader was compiled for.

Parse(ReadOnlySpan<byte>)

Reads a compiled shader file.

C#

public static CompiledShader Parse(ReadOnlySpan<byte> utf8Json)

Parameters

utf8Json ReadOnlySpan<byte>

Returns

CompiledShader

Exceptions

InvalidDataException

The data is not a compiled shader of a version this assembly reads.

ToBytes()

The file form of this shader (UTF-8 JSON, formats in a fixed order, so the same compilation gives the same bytes).

C#

public byte[] ToBytes()

Returns

byte[]

ToString()

C#

public override string ToString()

Returns

string

TryGetCode(ShaderFormat, out ShaderCode)

The code in format, if compiled for it.

C#

public bool TryGetCode(ShaderFormat format, out ShaderCode code)

Parameters

format ShaderFormat

code ShaderCode

Returns

bool