render_utils.h File Reference

Utilities for OpenGL rendering, focusing on robustness and NVIDIA compatibility. More...

#include "gl_common.h"
#include <stddef.h>

Include dependency graph for render_utils.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	GPUInfo
	Struct to hold GPU hardware and driver information. More...
struct	GLStateBackup
	Struct to backup common OpenGL state bits to restore after 2D/UI passes. More...

Functions
GLuint	render_utils_create_color_texture (float red, float green, float blue, float alpha)
	Creates a 1x1 floating-point texture of a specific color. More...
void	render_utils_bind_texture_safe (GLenum unit, GLuint texture, GLuint fallback_tex)
	Safely binds a texture to a specific unit, using a fallback if needed. More...
void	render_utils_reset_texture_units (int start_unit, int end_unit, GLuint fallback_tex)
	Resets a range of texture units to a safe state. More...
void	render_utils_create_empty_vao (GLuint *vao)
	Creates an empty Vertex Array Object (VAO). More...
void	render_utils_create_quad_vbo (GLuint *vbo)
	Creates a standard centered Quad VBO. More...
void	render_utils_create_wire_cube_vbo (GLuint *vbo)
	Creates a wireframe Unit Cube VBO (GL_LINES). More...
void	render_utils_create_wire_quad_vbo (GLuint *vbo)
	Creates a wireframe Quad VBO (GL_LINE_LOOP). More...
void	render_utils_create_fullscreen_quad (GLuint *vao, GLuint *vbo)
	Creates a Full-Screen Quad VAO and VBO. More...
GPUInfo	render_utils_get_gpu_info (void)
	Retrieves currently active GPU hardware and driver information. More...
void	render_utils_generate_gpu_identifier (const char *vendor, const char *renderer, char *buffer, size_t size)
	Sanitizes GPU vendor and renderer strings into a filesystem-safe identifier. More...
void	render_utils_get_gpu_identifier (char *buffer, size_t size)
	Generates a filesystem-safe identifier for the current GPU. More...
int	render_utils_check_framebuffer (const char *label)
	Checks the completeness of the currently bound framebuffer. More...
GLuint	render_utils_create_texture_2d (int width, int height, GLenum internal_format, GLint levels, const char *label)
	Creates a 2D texture with specified parameters. More...
void	render_utils_setup_sphere_instance_attributes (GLsizei stride, size_t offset_albedo, size_t offset_metallic)
	Sets up instance attributes for sphere rendering (Model, Albedo, PBR). More...
GLStateBackup	render_utils_save_state (void)
	Saves current OpenGL state to a backup struct. More...
void	render_utils_restore_state (const GLStateBackup *state)
	Restores OpenGL state from a backup struct. More...
void	render_utils_setup_ui_state (void)
	Configures standard 2D/UI rendering state (Alpha blend, No depth). More...

Detailed Description

Utilities for OpenGL rendering, focusing on robustness and NVIDIA compatibility.

This module encapsulates common rendering patterns, resource creation helpers, and specific "hacks" or best practices required to ensure stability across different GPU vendors, particularly NVIDIA. It provides tools for:

• Safe texture binding (handling missing textures without errors).
• Texture unit management (avoiding validation warnings).
• Standard geometry creation (Quads, Empty VAOs).
• Debugging helpers.

Function Documentation

render_utils_bind_texture_safe()

void render_utils_bind_texture_safe	(	GLenum	unit,
		GLuint	texture,
		GLuint	fallback_tex
	)

Safely binds a texture to a specific unit, using a fallback if needed.

This function ensures that a valid texture is always bound to the specified unit. If texture is 0 (invalid), it binds fallback_tex instead. This is critical for robustness, preventing GL errors or black screens when resources fail to load or are temporarily unavailable.

Parameters

unit	The texture unit to bind to (e.g., GL_TEXTURE0).
texture	The primary texture to bind.
fallback_tex	The fallback texture to use if texture is 0.

render_utils_check_framebuffer()

int render_utils_check_framebuffer

(

const char *

label

)

Checks the completeness of the currently bound framebuffer.

Logs an error message if the framebuffer is not complete.

Parameters

label

A string label to identify the framebuffer in logs.

Returns

1 if complete, 0 otherwise.

render_utils_create_color_texture()

GLuint render_utils_create_color_texture	(	float	red,
		float	green,
		float	blue,
		float	alpha
	)

Creates a 1x1 floating-point texture of a specific color.

Useful for creating "dummy" textures (e.g., black, white, normal) to bind to shader slots when a real texture is not available. This prevents undefined behavior or warnings from validation layers on some drivers (like NVIDIA) which check that all active samplers have valid textures.

Parameters

red	Red component (0.0 - 1.0).
green	Green component (0.0 - 1.0).
blue	Blue component (0.0 - 1.0).
alpha	Alpha component (0.0 - 1.0).

Returns

The GLuint handle of the created texture.

Here is the call graph for this function:

render_utils_create_empty_vao()

void render_utils_create_empty_vao

(

GLuint *

vao

)

Creates an empty Vertex Array Object (VAO).

Some OpenGL profiles (Core Profile) require a VAO to be bound for any draw call, even if the shader generates vertices without buffers (e.g., a full-screen triangle generated from gl_VertexID).

Parameters

[out]

vao

Pointer to store the generated VAO handle.

render_utils_create_fullscreen_quad()

void render_utils_create_fullscreen_quad	(	GLuint *	vao,
		GLuint *	vbo
	)

Creates a Full-Screen Quad VAO and VBO.

Generates a quad covering the entire Normalized Device Coordinates (NDC) space (-1.0 to 1.0). Used primarily for post-processing passes.

Includes:

• Positions (2 floats: x, y)
• Texture Coordinates (2 floats: u, v)

Parameters

[out]	vao	Pointer to store the generated VAO handle.
[out]	vbo	Pointer to store the generated VBO handle.

Here is the call graph for this function:

render_utils_create_quad_vbo()

void render_utils_create_quad_vbo

(

GLuint *

vbo

)

Creates a standard centered Quad VBO.

Generates a VBO containing vertices for a quad centered at (0,0) with size 1x1 (-0.5 to 0.5). Useful for billboard rendering or simple sprites.

Format: 3 floats (x, y, z) per vertex. Vertex count: 6 (2 triangles).

Parameters

[out]

vbo

Pointer to store the generated VBO handle.

render_utils_create_texture_2d()

GLuint render_utils_create_texture_2d	(	int	width,
		int	height,
		GLenum	internal_format,
		GLint	levels,
		const char *	label
	)

Creates a 2D texture with specified parameters.

Encapsulates glGenTextures, glBindTexture, glTexStorage2D (or equivalent), and basic parameter setup (MIN/MAG filters, WRAP S/T).

Parameters

width	Texture width.
height	Texture height.
internal_format	Internal GPU format (e.g., GL_RGBA16F).
levels	Number of mipmap levels.
label	Debug label for the texture.

Returns

The GLuint handle of the created texture.

render_utils_create_wire_cube_vbo()

void render_utils_create_wire_cube_vbo

(

GLuint *

vbo

)

Creates a wireframe Unit Cube VBO (GL_LINES).

Vertices range from -1.0 to 1.0. 12 edges * 2 vertices = 24 vertices.

Parameters

[out]

vbo

Pointer to store the generated VBO handle.

render_utils_create_wire_quad_vbo()

void render_utils_create_wire_quad_vbo

(

GLuint *

vbo

)

Creates a wireframe Quad VBO (GL_LINE_LOOP).

Vertices are: (-0.5, 0.5), (0.5, 0.5), (0.5, -0.5), (-0.5, -0.5). 4 vertices.

Parameters

[out]

vbo

Pointer to store the generated VBO handle.

render_utils_generate_gpu_identifier()

void render_utils_generate_gpu_identifier	(	const char *	vendor,
		const char *	renderer,
		char *	buffer,
		size_t	size
	)

Sanitizes GPU vendor and renderer strings into a filesystem-safe identifier.

Lowercases alphanumeric characters and collapses multiple separators into a single underscore.

Parameters

	vendor	The GPU vendor string.
	renderer	The GPU renderer string.
[out]	buffer	Destination buffer for the identifier.
	size	Size of the destination buffer.

Here is the call graph for this function:

render_utils_get_gpu_identifier()

void render_utils_get_gpu_identifier	(	char *	buffer,
		size_t	size
	)

Generates a filesystem-safe identifier for the current GPU.

Sanitizes vendor and renderer strings (lowercase, alphanumeric, underscores).

Parameters

[out]	buffer	Destination buffer for the identifier.
	size	Size of the destination buffer.

Here is the call graph for this function:

render_utils_get_gpu_info()

GPUInfo render_utils_get_gpu_info

(

void

)

Retrieves currently active GPU hardware and driver information.

Returns

A GPUInfo struct populated with current context data.

render_utils_reset_texture_units()

void render_utils_reset_texture_units	(	int	start_unit,
		int	end_unit,
		GLuint	fallback_tex
	)

Resets a range of texture units to a safe state.

Binds the fallback_tex (usually a dummy black texture) to all texture units from start_unit to end_unit.

Note

NVIDIA Specific: This is highly recommended before resizing framebuffers or deleting textures that might be currently bound. NVIDIA drivers can be very strict and may emit warnings or errors if you modify a texture that is still "active" in a sampler unit, even if not currently used by a shader. Resetting them ensures a clean state.

Parameters

start_unit	The starting texture unit index (0 for GL_TEXTURE0).
end_unit	The ending texture unit index (exclusive).
fallback_tex	The safe texture to bind.

render_utils_restore_state()

void render_utils_restore_state

(

const GLStateBackup *

state

)

Restores OpenGL state from a backup struct.

Parameters

state

Pointer to the state backup to restore.

render_utils_save_state()

GLStateBackup render_utils_save_state

(

void

)

Saves current OpenGL state to a backup struct.

render_utils_setup_sphere_instance_attributes()

void render_utils_setup_sphere_instance_attributes	(	GLsizei	stride,
		size_t	offset_albedo,
		size_t	offset_metallic
	)

Sets up instance attributes for sphere rendering (Model, Albedo, PBR).

Configures vertex attribute pointers for instanced arrays. Assumes the instance VBO is already bound.

Parameters

stride	Stride of the instance structure (sizeof(SphereInstance)).
offset_albedo	Byte offset of the albedo field.
offset_metallic	Byte offset of the metallic field (start of PBR block).

Here is the call graph for this function:

render_utils_setup_ui_state()

void render_utils_setup_ui_state

(

void

)

Configures standard 2D/UI rendering state (Alpha blend, No depth).