Rendering architecture: frame path and subsystems

This page maps the rendering data path in Reckfell 1.0.0 and helps locate a problem or extension point. The architecture was reviewed against current source. Execution evidence covers separate Windows/Vulkan Forward+ and Mobile scenarios, not every effect, driver or image-quality setting.

From Entity to frame

Entity / Resource
    |
RenderingServer / RID
    |
RendererSceneCull + RendererCanvasCull + RendererViewport
    |
    +-- Forward+ / Mobile --> RenderingDevice --> graphics driver --> GPU
    |
    +-- Compatibility ------> GLES3 renderer --> OpenGL driver --> GPU

MeshInstance3D uses Mesh and material resources. VisualInstance3D creates a server instance, assigns its base resource and updates transforms through RenderingServer. Multiple Entities can share one Mesh; instance placement and resource geometry are separate data. Entity count is not draw-call count: surfaces, materials, passes and shadows affect rendering work.

RenderingServer provides resource and rendering operations through RID. RendererSceneCull prepares the visible 3D scene, RendererCanvasCull handles canvas, and RendererViewport organizes camera and target-texture output. Direct server-resource use is possible, but its setup and lifetime become the caller’s responsibility.

RenderingDevice is lower level: textures, buffers, shaders, pipelines, uniform sets and draw/compute command lists. It does not automatically supply Material, camera, collision or visibility policy. Its command graph handles GPU-work dependencies; gameplay hierarchy remains in EntityTree.

Rendering method and driver

The method organizes rendering; the driver implements a graphics API. Startup code lists Vulkan, Direct3D 12 and Metal for Forward+/Mobile under corresponding build flags. Compatibility lists opengl3/opengl3_angle/opengl3_es. Driver source does not establish inclusion in a particular distribution or validation on your platform.

Record RenderingServer.GetCurrentRenderingMethod(), RenderingServer.GetCurrentRenderingDriverName(), GPU model and startup log together. The rendering/renderer/rendering_method setting alone is insufficient to diagnose every fallback. For example, RendererCompositorRD contains a clustered-to-Mobile fallback below 48 textures per shader stage; this is a source condition, not a test of such a GPU here.

Forward+ uses ClusterBuilderRD to prepare clustered data used for lighting. Mobile has separate pass and buffer organization; sharing RenderingDevice does not make feature sets identical. Compatibility has a separate GLES3 implementation. Choose using required features and target-scene measurements: the Mobile name alone guarantees no speed, nor Forward+ a finished high-quality image.

During drawing

RenderingServerDefault::_draw exposes these major steps:

1. Begin frame and prepare XR when enabled.
2. Update scene/canvas and particle data.
3. Prepare reflection probes.
4. Draw viewports.
5. Finish frame and dispatch visibility notifications.

Inside the 3D path RendererSceneCull prepares camera, visible instances and related light, GI, decal, lightmap and fog data. The selected implementation then receives render_scene. Actual GPU-pass order depends on the method and enabled features; the list above is not a fixed render-pass sequence.

Viewport determines target size, camera and output configuration. RenderSceneBuffersRD holds intermediate RD textures and pass data. Size, view count, MSAA and formats affect memory and reading availability. Do not assume every effect always receives identical color/depth textures or that private internal buffer names are public SDK contracts.

Visible is only one participation condition: camera, layers, distance, culling and resource readiness also matter. For a missing object, check the route to the intended viewport before material/geometry, rather than starting with a driver change.

Project shaders and engine shaders

Shader sends prepared code through RenderingServer.shader_set_code. Material passes parameters and resource references; BaseMaterial3D generates code from its enabled features. A parameter change and a material-feature change can therefore have different preparation costs.

Internal RD/GLES3 shaders implement rendering stages. Their sources and generated headers are part of the engine build. Editing such a GLSL file in the repository does not change an already installed binary; applying the change requires the corresponding build. Project shaders use a different storage/compilation route. For an application effect start with the shading language, before changing a shared engine material shader.

First use of a new variant can include shader/pipeline preparation. This is a different source of delay from steady per-frame cost. Measure first use and the settled scene separately; this page establishes neither duration on your device.

Subsystem map

Paths below are relative to the local Source tree. They navigate source; they are not downloadable archives.

An effect module does not establish support in every method. Use the feature guide for settings and limitations: volumetric fog, VRS. Import-time mesh LOD generation, camera LOD selection and occlusion rejection solve different tasks; distinguish them when investigating disappearing geometry.

Extending through Compositor

CompositorEffect receives RenderData at its selected rendering stage. This route exposes prepared scene buffers and requires the right stage, format, dimensions and lifetime.

In the retained Mobile run PostOpaque produced a warning and PostSky was not called. An enum value alone does not make an effect portable between methods. Camera.Compositor replaces the world compositor; even an empty camera compositor overrides the world list. This behavior was executed in the engine.

PostTransparent in the checked RD path precedes postprocessing and tonemap. Do not assume it is the final displayed image. Read buffers and RenderData inside the callback; do not keep borrowed frame data as long-lived resources. Contracts and example: CompositorEffect.

Threads, RID and GPU readback

RenderingServerDefault has a command queue and an optional separate render thread. A CPU call and completed GPU work are different events. Use the appropriate render-thread context for main RenderingDevice operations, such as a CompositorEffect callback; check scene-tree thread contracts before moving scene operations there.

GetRenderingDevice returns the engine’s shared device. CreateLocalRenderingDevice requires an available main RD and creates a separate device; it does not supply a missing RD in Compatibility. RIDs belong to the subsystem/device that created them. RenderingServer.FreeRid and RenderingDevice.FreeRid are not interchangeable. Do not free borrowed viewport-buffer RIDs as owned resources.

Rid.IsValid checks a nonzero identifier rather than resource existence in an owner. Freeing a resource does not automatically zero saved RID copies. Maintain explicit ownership, especially when releasing callback resources.

Synchronous RD texture_get_data can force pending GPU work to complete. Measure before adding continuous CPU image readback to the ordinary frame path; texture-content inspection and an efficient effect are different scenarios.

Symptom-based diagnosis

Verification coverage

Forty earlier Windows/Vulkan Forward+/Mobile observations were reused: Compositor stages, camera override, color/depth/view-count access and VRS attachment allocation. Runtime, SDK and test assets were checked again; GPU scenes were not rerun. Identity verification includes launching console --version.

Original reports retain a Vulkan-loader warning and an unsupported Mobile-stage warning. Their negative status was not changed to positive. They establish bounded scenarios and structure, not acceptance of the whole renderer. D3D12, Metal, Compatibility, GI/TAA/DOF quality, FPS, MSAA, stereo, export and visual quality were not checked by this page. Engine code, SDK and installed Runtime were unchanged.