nCine::RHI::Metal::MetalShaderProgram class
#include <nCine/Graphics/RHI/Metal/MetalShaderProgram.h>

Shader program of the Metal backend (aliased as RHI::ShaderProgram).

Carries the offline ShaderCompiler reflection (set with SetReflection() like the OpenGL backend) from which it imports uniforms, uniform blocks and attributes so the pipeline's uniform machinery runs. It also compiles the reflection's embedded MslVsSource/MslFsSource into an MTL::Library per stage at link time (there is no offline MSL compiler outside Xcode; Metal's own compiler service caches the result per source across runs) and keeps the two MTL::Function objects, and it derives the argument table the device binds each draw from the same reflection (the _Globals buffer at index 0, then the std140 blocks, then the texture/sampler pairs, in reflection order - the scheme the MSL emitter writes). The MTL::RenderPipelineState objects themselves are cached by the device per vertex format, blend state and attachment formats. Use() records the program as current on the device.

Public types

struct DescriptorBinding
One entry of the program's argument table, matching the offline emitter's binding scheme.
struct LooseUniform
A loose (default-block) uniform gathered into the "_Globals" buffer, with its std140 placement.
struct VertexAttrib
A vertex attribute for building the pipeline's vertex descriptor.
enum class Introspection { Enabled, NoUniformsInBlocks, Disabled }
enum class Status { NotLinked, CompilationFailed, LinkingFailed, Linked, LinkedWithDeferredQueries, LinkedWithIntrospection }
enum class QueryPhase { Immediate, Deferred }

Public static variables

static std::int32_t DefaultBatchSize constexpr
Default batch size, indicating the shader is not batched.

Constructors, destructors, conversion operators

MetalShaderProgram()
MetalShaderProgram(QueryPhase queryPhase) explicit
MetalShaderProgram(StringView vertexFile, StringView fragmentFile, Introspection introspection, QueryPhase queryPhase)
MetalShaderProgram(StringView vertexFile, StringView fragmentFile, Introspection introspection)
MetalShaderProgram(StringView vertexFile, StringView fragmentFile)
~MetalShaderProgram()
MetalShaderProgram(const MetalShaderProgram&) deleted

Public functions

auto operator=(const MetalShaderProgram&) -> MetalShaderProgram& deleted
auto GetUniqueId() const -> std::uint32_t
Returns a backend-neutral identifier uniquely identifying the program (feeds material sort keys; also keys the device's pipeline cache).
auto GetStatus() const -> Status
auto GetIntrospection() const -> Introspection
auto GetQueryPhase() const -> QueryPhase
auto GetBatchSize() const -> std::uint32_t
void SetBatchSize(std::uint32_t value)
auto IsLinked() const -> bool
auto RetrieveInfoLogLength() const -> std::uint32_t
void RetrieveInfoLog(std::string& infoLog) const
auto GetUniformsSize() const -> std::uint32_t
auto GetUniformBlocksSize() const -> std::uint32_t
auto AttachShaderFromFile(ShaderStage stage, StringView filename) -> bool
auto AttachShaderFromString(ShaderStage stage, StringView string) -> bool
auto AttachShaderFromStrings(ShaderStage stage, ArrayView<const StringView> strings) -> bool
auto AttachShaderFromStringsAndFile(ShaderStage stage, ArrayView<const StringView> strings, StringView filename) -> bool
void SetReflection(const ShaderCompiler::ProgramVariant* reflection)
Sets the offline reflection consumed by Link() to import uniforms/blocks/attributes and compile the MSL.
void SetProgramIdentity(const char* programName, const char* variantName)
Records the true (program, variant) identity of the loaded shader.
auto Link(Introspection introspection) -> bool
void Use()
auto Validate() -> bool
auto FinalizeAfterLinking(Introspection introspection) -> bool
auto GetAttributeCount() const -> std::uint32_t
auto HasAttribute(const char* name) const -> bool
auto GetAttribute(const char* name) -> MetalVertexFormat::Attribute*
void DefineVertexFormat(const MetalBufferObject* vbo)
void DefineVertexFormat(const MetalBufferObject* vbo, const MetalBufferObject* ibo)
void DefineVertexFormat(const MetalBufferObject* vbo, const MetalBufferObject* ibo, std::uint32_t vboOffset)
void Reset()
void SetObjectLabel(StringView label)
auto GetLogOnErrors() const -> bool
void SetLogOnErrors(bool shouldLogOnErrors)
void SetResolvedUniform(const char* name, const std::uint8_t* data)
Publishes a committed loose-uniform value pointer for the device to gather into _Globals.
auto ResolveUniform(const char* name) const -> const std::uint8_t*
Returns the last published value pointer of the named loose uniform, or nullptr.
auto HasVertexAttributes() const -> bool
Returns true if the vertex shader reads vertex attributes (needs a vertex descriptor + a vertex buffer).
auto GetBoundVbo() const -> const MetalBufferObject*
Returns the vertex buffer bound by DefineVertexFormat(), or nullptr.
auto GetBoundIbo() const -> const MetalBufferObject*
Returns the index buffer bound by DefineVertexFormat(), or nullptr.
auto HasPipelineState() const -> bool
Returns true if both stage functions compiled (draws are skipped otherwise).
auto GetVsFunction() const -> void*
The vertex-stage MTL::Function* (as void*).
auto GetFsFunction() const -> void*
The fragment-stage MTL::Function*.
auto GetDescriptorBindings() const -> const std::vector<DescriptorBinding>&
The argument bindings (in reflection order) the device sets each draw.
auto GetLooseUniforms() const -> const std::vector<LooseUniform>&
The loose uniforms gathered into "_Globals" (empty if the program has none).
auto GetGlobalsSize() const -> std::uint32_t
std140 byte size of the "_Globals" buffer (0 if the program has no loose uniforms)
auto HasGlobals() const -> bool
Whether the program has a "_Globals" buffer (always at buffer index 0 when present).
auto GetVertexInput(VertexAttrib* outAttribs, std::uint32_t maxAttribs, std::uint32_t& outStride, std::uint32_t& outBaseOffset) const -> std::uint32_t
Fills the current vertex input layout (attributes + per-vertex stride + buffer base offset) from the bound vertex format.

Function documentation

void nCine::RHI::Metal::MetalShaderProgram::SetProgramIdentity(const char* programName, const char* variantName)

Records the true (program, variant) identity of the loaded shader.

Only the fixed-function console backends consume it (they resolve their generated effect tables from this identity instead of the object label); this backend runs real shaders and ignores it.

std::uint32_t nCine::RHI::Metal::MetalShaderProgram::GetVertexInput(VertexAttrib* outAttribs, std::uint32_t maxAttribs, std::uint32_t& outStride, std::uint32_t& outBaseOffset) const

Fills the current vertex input layout (attributes + per-vertex stride + buffer base offset) from the bound vertex format.

Writes at most maxAttribs entries into outAttribs (a caller-provided array, so the per-draw pipeline-key computation never touches the heap) and returns the number written. outBaseOffset is the byte offset within the vertex buffer the layout starts at (the vboOffset of DefineVertexFormat()).