Renderer

Renderer interface for drawing a scene with a given camera.

The renderer owns GPU state and draw logic for rendering a Scene with a specified Camera. Construct one alongside your Window, and call Render once per frame.

This class defines the rendering interface only. The actual rendering implementation is provided by a backend, and multiple backends (for example, OpenGL or Vulkan) may exist behind this interface.

vglx::Renderer renderer({
  .clear_color = 0x444444u
});

auto ok = renderer.Initialize(window);
if (!ok) {
  HandleError(ok.error());
}

Once initialized, the renderer reads the framebuffer size and content scale from the window at the start of every frame, so the viewport follows window resizes without any user code. Call SetViewport only to draw into a sub-region of the framebuffer. The renderer must be destroyed before the window it was initialized with.

Construction

Constructors

Renderer()

Constructs a renderer.

GPU resources are not created until Initialize is called.

Renderer::Renderer(const Renderer::Parameters& params);

Parameter	Description
params	Initialization parameters for constructing the renderer.

Types

Renderer::ShadowMap enum

Shadow mapping method applied to shadow-casting lights.

Value	Description
None	Shadows disabled.
Basic	Single-sample depth-mapped shadows with hard edges.
PCF	Percentage-closer filtered (PCF) shadows with soft edges.

Renderer::ToneMapping enum

Tone mapping operator applied to the final HDR frame before display.

Value	Description
None	No tone mapping. HDR values are clamped to [0, 1].
ACESFilmic	ACES filmic curve. Compresses highlights and preserves shadows.

Renderer::DriverInfo struct

Driver and hardware identity strings reported by the rendering backend.

Parameter	Description
vendor std::string	Driver vendor string.
renderer std::string	Hardware renderer string.
version std::string	Graphics API version string.
glsl_version std::string	Shading language version string.

Renderer::Limits struct

Hardware limits reported by the rendering backend.

Parameter	Description
max_anisotropy float	Max anisotropy for texture sampling.
max_samples int	Max MSAA sample count.
max_texture_units int	Max texture units per shader.
max_texture_size int	Max 2D texture dimension.
max_cube_map_size int	Max cube map face dimension.
max_renderbuffer_size int	Max renderbuffer dimension.

Renderer::Parameters struct

Parameters for constructing a Renderer object.

Parameter	Description
sample_count int	Antialiasing level (e.g., 4x MSAA).
clear_color Color	Clear color used at the start of a frame.
auto_clear bool	Automatic buffer clearing at the start of a frame.
tone_mapping ToneMapping	Tone mapping operator applied to the final frame.
exposure float	Exposure scale applied to HDR values before tone mapping.
shadow_map ShadowMap	Shadow mapping method applied to the scene.

Renderer::Viewport struct

Viewport rectangle in framebuffer pixels.

The origin is the bottom-left corner of the framebuffer.

Parameter	Description
x int	Left edge in pixels.
y int	Bottom edge in pixels.
width int	Width in pixels.
height int	Height in pixels.

Functions

Clear() void

Clears the color and depth buffers of the given target.

Intended for compositing flows where automatic clearing is disabled (see SetAutoClear). Call it once at the start of a frame, then render multiple scenes into the same target.

void Renderer::Clear(RenderTarget* target=nullptr);

Parameter	Description
target	Pointer to the render target to clear or nullptr for default framebuffer.

GetDriverInfo() const DriverInfo&

Returns driver and hardware identity strings reported by the rendering backend.

Must be called after Initialize has succeeded.

const DriverInfo& Renderer::GetDriverInfo() const;

GetLimits() const Limits&

Returns hardware limits reported by the rendering backend.

Must be called after Initialize has succeeded.

const Limits& Renderer::GetLimits() const;

Initialize() std::expected<void, std::string>

Initializes GPU state and binds the renderer to a window.

The window must be initialized first. From this point on the renderer reads the framebuffer size and content scale from the window at the start of every frame that targets the default framebuffer so resizes are handled automatically. The renderer keeps a reference to the window for its lifetime and must be destroyed before it.

std::expected<void, std::string> Renderer::Initialize(Window& window);

Parameter	Description
window	The window whose framebuffer the renderer presents to.

Render() void

Renders the given scene from the specified camera.

The scene is expected to be in a consistent state for rendering. If you are using the runtime path, this is handled automatically. In direct initialization flows, call the per-frame update routine Scene::Advance prior to rendering.

When rendering to the default framebuffer, the scene's canvas is drawn on top of the tone-mapped frame in display space. Canvas is skipped when rendering to a render target.

void Renderer::Render(Scene* scene, Camera* camera, RenderTarget* target=nullptr);

Parameter	Description
scene	Pointer to the scene to render.
camera	Pointer to the active camera.
target	Pointer to the render target to clear or nullptr for default framebuffer.

RenderedObjectsPerFrame() size_t

Returns the number of renderable objects drawn in the last frame.

Intended for statistics overlays and debugging.

size_t Renderer::RenderedObjectsPerFrame() const;

SetAutoClear() void

Sets whether the color and depth buffers are cleared before drawing.

When enabled (the default), each call to Render clears the color and depth buffers before drawing. Disable it to composite multiple scenes into the same frame, such as rendering a screen-space overlay on top of a previously rendered scene, using Clear to clear explicitly when needed.

void Renderer::SetAutoClear(bool auto_clear);

Parameter	Description
auto_clear	Clear the depth and color buffers automatically at the start of each frame.

SetClearColor() void

Sets the clear color for subsequent frames.

The color is applied at the start of each frame when the framebuffer is cleared. Typically used to define the background color of the rendering surface.

void Renderer::SetClearColor(const Color& color);

Parameter	Description
color	Clear color in RGB format.

SetExposure() void

Sets the exposure scale for subsequent frames.

Multiplies HDR color values before tone mapping is applied. Higher values brighten the image; lower values darken it.

void Renderer::SetExposure(float exposure);

Parameter	Description
exposure	Linear exposure multiplier. Defaults to 1.0.

SetShadowMap() void

Sets the shadow mapping method for subsequent frames.

Switching methods may compile new shader variants on the next frame. Selecting ShadowMap::None releases all shadow map resources. Switching back re-creates them on demand.

void Renderer::SetShadowMap(ShadowMap shadow_map);

Parameter	Description
shadow_map	Shadow mapping method to apply.

SetToneMapping() void

Sets the tone mapping operator for subsequent frames.

Changes how HDR color values are mapped to the display range. Takes effect immediately on the next call to Render.

void Renderer::SetToneMapping(ToneMapping tone_mapping);

Parameter	Description
tone_mapping	Tone mapping operator to apply.

SetViewport() void

Pins the viewport to an explicit rectangle.

By default the viewport covers the full framebuffer of the window passed to Initialize and follows it across resizes. Calling this method replaces that behavior with a fixed rectangle.

void Renderer::SetViewport(const Viewport& viewport);

Parameter	Description
viewport	Viewport rectangle to draw into, in framebuffer pixels.