nCine::RHI::GXM::GxmShaderProgram class
#include <nCine/Graphics/RHI/GXM/GxmShaderProgram.h>

Shader program of the sceGxm 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, and gets its two stage sources from the identity SetProgramIdentity() plumbs in - the generated CgGeneratedShaders.h table, which the Cg emitter fills offline. The sources are Cg, so they are compiled on the console by SceShaccCg (through vitaShaRK's shark_compile_shader()) when the program links: sceGxm consumes GXP binaries and the SDK ships no offline compiler for them, so libshacccg.suprx from the console's own firmware is a hard requirement of this backend - GxmDevice::CreateSwapchain() says so explicitly if it is missing.

Linking then registers both stages with the shader patcher and reflects their parameters into the GxmUniformSlot tables the draw path uploads through. The two patched programs sceGxm actually binds are created on demand and cached, because neither is a property of the shader alone:

a vertex program bakes in the vertex layout, so there is one per GxmVertexFormat the pipeline binds (usually exactly one),
a fragment program bakes in the blend state, so there is one per blend configuration the material sorting produces (a handful: opaque, alpha-blended, additive, ...).

Public types

struct GxmBlockUpload: Where one uniform block's bytes go in a stage's default uniform buffer.
struct GxmSamplerSlot: Where one of a stage's samplers takes its texture from.
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.

Public static functions

static auto PackBlendKey(bool enabled, nCine::BlendingFactor srcRgb, nCine::BlendingFactor dstRgb, nCine::BlendingFactor srcAlpha, nCine::BlendingFactor dstAlpha) -> std::uint32_t: Packs a blend configuration into the key GetFragmentProgram() caches on.
static auto FindAttribute(const SceGxmProgram* program, const char* name) -> const SceGxmProgramParameter*: Resolves a vertex attribute of a compiled stage by the name the engine knows it under.
static auto FindUniformBase(const SceGxmProgram* program, const char* name, GxmBlockUpload::Destination& destination, std::uint32_t& index) -> bool: Resolves where a named block member lives in the compiled stage.
static void InstallCompilerLogCallback(): Routes SceShaccCg's diagnostics into the engine log.
static auto CompileCgStage(const char* source, bool vertexStage, std::uint32_t& sizeInBytes) -> SceGxmProgram*: Compiles one Cg stage on the console and returns a GXP binary the caller owns.

Constructors, destructors, conversion operators

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

Public functions

auto operator=(const GxmShaderProgram&) -> GxmShaderProgram& deleted
auto GetUniqueId() const -> std::uint32_t: Returns a backend-neutral identifier uniquely identifying the program (feeds material sort keys).
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.
void SetProgramIdentity(const char* programName, const char* variantName): Records the true (program, variant) identity of the loaded shader.
auto GetProgramName() const -> const char*: Returns the generated program's name, or nullptr for one that carries no identity.
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 IsIntegerAttribute(const char* name) const -> bool: Returns true if the reflection declares name with an integer type (a batch element index).
auto GetAttribute(const char* name) -> GxmVertexFormat::Attribute*
void DefineVertexFormat(const GxmBufferObject* vbo)
void DefineVertexFormat(const GxmBufferObject* vbo, const GxmBufferObject* ibo)
void DefineVertexFormat(const GxmBufferObject* vbo, const GxmBufferObject* 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 upload.
auto ResolveUniform(const char* name) const -> const std::uint8_t*: Returns the last published value pointer of the named loose uniform, or nullptr.
auto GetVertexStage() const -> const SceGxmProgram*: Returns the compiled vertex stage, or nullptr if the program did not link.
auto GetFragmentStage() const -> const SceGxmProgram*: Returns the compiled fragment stage, or nullptr.
auto GetVertexProgram() -> SceGxmVertexProgram*: Returns/creates the patched vertex program for the currently bound vertex format, or nullptr.
auto GetFragmentProgram(std::uint32_t blendKey, const SceGxmBlendInfo* blendInfo) -> SceGxmFragmentProgram*: Returns/creates the patched fragment program for a blend configuration, or nullptr.
auto GetVertexUniformBufferSize() const -> std::uint32_t: Returns the byte size of the vertex stage's default uniform buffer.
auto GetFragmentUniformBufferSize() const -> std::uint32_t: Returns the byte size of the fragment stage's default uniform buffer.
auto GetVertexUniformSlots() const -> const SmallVector<GxmUniformSlot, 0>&: Loose-uniform slots of the vertex stage (resolved once at link time).
auto GetFragmentUniformSlots() const -> const SmallVector<GxmUniformSlot, 0>&: Loose-uniform slots of the fragment stage.
auto GetVertexBlockUploads() const -> const SmallVector<GxmBlockUpload, 0>&: Uniform-block member uploads of the vertex stage.
auto GetFragmentBlockUploads() const -> const SmallVector<GxmBlockUpload, 0>&: Uniform-block member uploads of the fragment stage.
auto GetVertexSamplerSlots() const -> const SmallVector<GxmSamplerSlot, 0>&: Sampler slots of the vertex stage (rare, but sceGxm allows vertex texturing).
auto GetFragmentSamplerSlots() const -> const SmallVector<GxmSamplerSlot, 0>&: Sampler slots of the fragment stage.
auto HasVertexAttributes() const -> bool: Returns true if the vertex stage reads any vertex attribute.
auto GetStageAttributes() const -> const SmallVector<GxmStageAttribute, 4>&: Returns the vertex attributes the compiled stage declares (see GxmStageAttribute).
auto GetBoundVbo() const -> const GxmBufferObject*: Returns the vertex buffer bound by DefineVertexFormat(), or nullptr.
auto GetBoundIbo() const -> const GxmBufferObject*: Returns the index buffer bound by DefineVertexFormat(), or nullptr.
auto GetVboOffset() const -> std::uint32_t: Returns the byte offset into the bound vertex buffer the attributes start at.
auto UsesStaticCornerStream() const -> bool: Returns true if the vertex layout takes its corner (and instance index) from a device static stream.
auto UsesBatchedCornerStream() const -> bool: Returns true if the static stream is the batched one (six vertices per sprite, with an instance index).
auto UsesGeometryStream() const -> bool: Returns true if the vertex layout reads any attribute out of the pipeline's vertex buffer.
auto GetStaticStreamIndex() const -> std::uint32_t: Returns the sceGxm stream index the static corner stream is bound to (0 when there is no geometry stream).
auto GetGeometryStride() const -> std::uint32_t: Returns the per-vertex byte stride of the geometry stream.

Function documentation

static const SceGxmProgramParameter* nCine::RHI::GXM::GxmShaderProgram::FindAttribute(const SceGxmProgram* program, const char* name)

Resolves a vertex attribute of a compiled stage by the name the engine knows it under.

The reflected name of an attribute the entry point receives through an input struct is not guaranteed to be the bare member name - a qualified <struct>.<member> form is equally plausible and only the compiler decides - so an exact match is tried first and a match on the last dot-separated component second. Returns nullptr and logs the stage's whole attribute list when neither resolves, because a silently dropped attribute renders nothing and explains nothing.

static bool nCine::RHI::GXM::GxmShaderProgram::FindUniformBase(const SceGxmProgram* program, const char* name, GxmBlockUpload::Destination& destination, std::uint32_t& index)

Resolves where a named block member lives in the compiled stage.

Returns	`false` if the stage has no uniform belonging to that name at all

Handles all three shapes a member can take: a uniform in the default buffer, a uniform buffer container (the batched instance array), and an array of structs named only through its leaves.

static void nCine::RHI::GXM::GxmShaderProgram::InstallCompilerLogCallback()

Routes SceShaccCg's diagnostics into the engine log.

Called once before anything is compiled - including the device's own built-in shaders, which otherwise fail with no explanation but the caller's own message.

static SceGxmProgram* nCine::RHI::GXM::GxmShaderProgram::CompileCgStage(const char* source, bool vertexStage, std::uint32_t& sizeInBytes)

Compiles one Cg stage on the console and returns a GXP binary the caller owns.

Parameters
source	Cg source, null-terminated
vertexStage	`true` for a vertex stage, `false` for a fragment one
sizeInBytes	Receives the size of the returned binary
Returns	A GXP binary to release with `std::free()`, or `nullptr` if the compile failed

This exists to contain a trap. shark_compile_shader() hands back a pointer into SceShaccCg's compile output (SceShaccCgCompileOutput::programData), not a copy of it, and shark_clear_output() releases that output through sceShaccCgDestroyCompileOutput() - so clearing the output, as any tidy caller would, leaves the returned SceGxmProgram* dangling. The symptom is not a crash at the free: the program reads back with zero reflected parameters and faults later inside the shader patcher, which points at everything except the real cause. The bytes are therefore copied out before the output is cleared, which is also what sceGxm requires - a registered program's memory has to stay alive for as long as it is registered.

void nCine::RHI::GXM::GxmShaderProgram::SetProgramIdentity(const char* programName, const char* variantName)

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

This backend resolves its generated Cg stage sources from this identity, the same way the fixed-function console backends resolve their generated effect tables from it.

SceGxmFragmentProgram* nCine::RHI::GXM::GxmShaderProgram::GetFragmentProgram(std::uint32_t blendKey, const SceGxmBlendInfo* blendInfo)

Returns/creates the patched fragment program for a blend configuration, or nullptr.

Parameters
blendKey	Packed blend state from PackBlendKey(), the cache's key
blendInfo	The blend state to bake in, or `nullptr` for opaque (blending disabled)

nCine::RHI::GXM::GxmShaderProgram class #include <nCine/Graphics/RHI/GXM/GxmShaderProgram.h>