nCine::GLShaderProgram class
#include <nCine/Graphics/GL/GLShaderProgram.h>

Wraps an OpenGL shader program object.

Manages the lifetime of a shader program, attaches GLShader objects, links and optionally validates them, and binds the program for rendering (caching the currently bound program to avoid redundant glUseProgram() calls). After linking it can introspect the program to discover active uniforms, uniform blocks and vertex attributes, and to build the associated vertex format. Compilation and linking queries can be performed immediately or deferred until the program is first used.

Public types

enum class Introspection { Enabled, NoUniformsInBlocks, Disabled }: How much of the program is introspected after linking.
enum class Status { NotLinked, CompilationFailed, LinkingFailed, Linked, LinkedWithDeferredQueries, LinkedWithIntrospection }: Lifecycle status of the shader program.
enum class QueryPhase { Immediate, Deferred }: When compilation and linking status are queried.

Public static variables

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

Constructors, destructors, conversion operators

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

Public functions

auto operator=(const GLShaderProgram&) -> GLShaderProgram& deleted
auto GetGLHandle() const -> GLuint: Returns the OpenGL handle of the shader program object.
auto GetStatus() const -> Status: Returns the current lifecycle status.
auto GetIntrospection() const -> Introspection: Returns the introspection level used when linking.
auto GetQueryPhase() const -> QueryPhase: Returns when compilation and linking status are queried.
auto GetBatchSize() const -> std::uint32_t: Returns the batch size, or DefaultBatchSize if the shader is not batched.
void SetBatchSize(std::uint32_t value): Sets the batch size used for batched rendering.
auto IsLinked() const -> bool: Returns true if the program has been linked successfully.
auto RetrieveInfoLogLength() const -> std::uint32_t: Returns the length of the information log, including the null terminator.
void RetrieveInfoLog(std::string& infoLog) const: Retrieves the information log.
auto GetUniformsSize() const -> std::uint32_t: Returns the total memory needed for all uniforms outside of blocks.
auto GetUniformBlocksSize() const -> std::uint32_t: Returns the total memory needed for all uniforms inside of blocks.
auto AttachShaderFromFile(GLenum type, StringView filename) -> bool: Attaches a shader stage compiled from the specified file.
auto AttachShaderFromString(GLenum type, StringView string) -> bool: Attaches a shader stage compiled from the specified source string.
auto AttachShaderFromStrings(GLenum type, ArrayView<const StringView> strings) -> bool: Attaches a shader stage compiled from the specified source strings.
auto AttachShaderFromStringsAndFile(GLenum type, ArrayView<const StringView> strings, StringView filename) -> bool: Attaches a shader stage compiled from the specified source strings and file.
auto Link(Introspection introspection) -> bool: Links the attached shaders into the program.
void Use(): Binds the program for rendering.
auto Validate() -> bool: Validates the program and returns true if validation succeeded.
auto FinalizeAfterLinking(Introspection introspection) -> bool: Finalizes the program after an external link step.
auto GetAttributeCount() const -> std::uint32_t: Returns the number of active vertex attributes discovered by introspection.
auto HasAttribute(const char* name) const -> bool: Returns true if the program has an active vertex attribute with the given name.
auto GetAttribute(const char* name) -> GLVertexFormat::Attribute*: Returns the vertex format attribute with the given name, or nullptr if not found.
void DefineVertexFormat(const GLBufferObject* vbo): Defines the vertex format from a vertex buffer object.
void DefineVertexFormat(const GLBufferObject* vbo, const GLBufferObject* ibo): Defines the vertex format from a vertex buffer object and an index buffer object.
void DefineVertexFormat(const GLBufferObject* vbo, const GLBufferObject* ibo, std::uint32_t vboOffset): Defines the vertex format from the given buffer objects.
void Reset(): Resets the program so that new shaders can be attached.
void SetObjectLabel(StringView label): Sets an OpenGL object label for the program, for debugging.
auto GetLogOnErrors() const -> bool: Returns the automatic log on errors flag.
void SetLogOnErrors(bool shouldLogOnErrors): Sets the automatic log on errors flag.

Enum documentation

enum class nCine::GLShaderProgram::Introspection

How much of the program is introspected after linking.

Enumerators
Enabled	Discover all uniforms, including those inside uniform blocks
NoUniformsInBlocks	Discover uniforms and uniform blocks, but not the uniforms inside the blocks
Disabled	Perform no introspection

enum class nCine::GLShaderProgram::Status

Lifecycle status of the shader program.

Enumerators
NotLinked	Not linked yet
CompilationFailed	Compilation of an attached shader failed
LinkingFailed	Linking failed
Linked	Linked successfully
LinkedWithDeferredQueries	Linked, but the status checks and introspection are still pending
LinkedWithIntrospection	Linked and introspected

enum class nCine::GLShaderProgram::QueryPhase

When compilation and linking status are queried.

Enumerators
Immediate	Status is checked and introspection is performed right after linking
Deferred	Status checks and introspection are postponed until the program is first used

Function documentation

void nCine::GLShaderProgram::RetrieveInfoLog(std::string& infoLog) const

Retrieves the information log.

Copies the program information log into the provided string, up to its current capacity.

bool nCine::GLShaderProgram::AttachShaderFromFile(GLenum type, StringView filename)

Attaches a shader stage compiled from the specified file.

Parameters
type	The shader stage (e.g. `GL_VERTEX_SHADER`)
filename	Path of the file containing the shader source
Returns	`true` if the shader compiled successfully (or when checks are deferred)

bool nCine::GLShaderProgram::AttachShaderFromString(GLenum type, StringView string)

Attaches a shader stage compiled from the specified source string.

Parameters
type	The shader stage (e.g. `GL_VERTEX_SHADER`)
string	The shader source
Returns	`true` if the shader compiled successfully (or when checks are deferred)

bool nCine::GLShaderProgram::AttachShaderFromStrings(GLenum type, ArrayView<const StringView> strings)

Attaches a shader stage compiled from the specified source strings.

Parameters
type	The shader stage (e.g. `GL_VERTEX_SHADER`)
strings	The shader source fragments, concatenated in order
Returns	`true` if the shader compiled successfully (or when checks are deferred)

bool nCine::GLShaderProgram::AttachShaderFromStringsAndFile(GLenum type, ArrayView<const StringView> strings, StringView filename)

Attaches a shader stage compiled from the specified source strings and file.

Parameters
type	The shader stage (e.g. `GL_VERTEX_SHADER`)
strings	The shader source fragments, concatenated in order
filename	Path of a file whose source is appended after the strings
Returns	`true` if the shader compiled successfully (or when checks are deferred)

bool nCine::GLShaderProgram::Link(Introspection introspection)

Links the attached shaders into the program.

Parameters
introspection	The introspection level to use after linking
Returns	`true` on success, or when the status check is deferred

void nCine::GLShaderProgram::Use()

Binds the program for rendering.

Processes any deferred queries on first use and calls glUseProgram(), skipping it if the program is already bound.

bool nCine::GLShaderProgram::FinalizeAfterLinking(Introspection introspection)

Finalizes the program after an external link step.

Parameters
introspection	The introspection level to use
Returns	`true` on success, or when the status check is deferred

When queries are immediate, checks the link status, detaches the shader objects and performs introspection; otherwise marks the program for deferred queries.

void nCine::GLShaderProgram::DefineVertexFormat(const GLBufferObject* vbo, const GLBufferObject* ibo, std::uint32_t vboOffset)

Defines the vertex format from the given buffer objects.

Parameters
vbo	The vertex buffer object providing attribute data
ibo	The index buffer object, or `nullptr` if unused
vboOffset	Base offset into the vertex buffer applied to every attribute

Assigns the vertex and index buffers to the introspected attributes and binds a matching VAO.

void nCine::GLShaderProgram::Reset()

Resets the program so that new shaders can be attached.

Clears the introspection state, deletes the current OpenGL program and creates a fresh one.

void nCine::GLShaderProgram::SetLogOnErrors(bool shouldLogOnErrors)

Sets the automatic log on errors flag.

When true, the shader program automatically logs compilation and linking errors.

nCine::GLShaderProgram class #include <nCine/Graphics/GL/GLShaderProgram.h>