Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/armory3d/armorpaint/llms.txt

Use this file to discover all available pages before exploring further.

ArmorPaint includes the Brute Pathtracer, a custom-built path-tracing engine that trades strict physical correctness for real-time interactivity. Rather than converging to a ground-truth solution over thousands of samples, it runs on hardware-accelerated ray tracing and is designed to give you a high-quality, near-photorealistic viewport preview that updates as you paint. The Brute Pathtracer runs on Direct3D 12 (via DXR), Vulkan (via Vulkan RT), and Metal (via Metal RT), and is used both for the live path-traced viewport mode and for ray-traced texture baking features such as ambient occlusion, lightmaps, bent normals, and thickness.

​
Hardware Requirements

Path tracing is only available on GPUs with dedicated hardware ray-tracing support. Attempting to enable path-traced modes on unsupported hardware will have no effect or may cause the renderer to fall back silently.Minimum requirements by platform:
PlatformAPIRequirement
WindowsDirect3D 12DXR-capable GPU (NVIDIA Turing / Ampere / Ada, AMD RDNA 2+, Intel Arc)
Windows / LinuxVulkanVulkan 1.2 + VK_KHR_ray_tracing_pipeline extension
macOSMetalApple Silicon (M1 and later) or AMD GCN-based GPU with Metal RT support

​
Path Trace Modes

The Brute Pathtracer operates in one of two modes, controlled by the pathtrace_mode_t enum and stored in the pathtrace_mode config field:
PATHTRACE_MODE_FAST — Optimised for real-time interactivity. Most advanced shading features are disabled to maximise frame rate, delivering rapid viewport feedback while you paint. The engine loads the raytrace_brute_core shader variant in this mode.
// From render_path_raytrace.c
char *mode = g_config->pathtrace_mode == PATHTRACE_MODE_FAST ? "core" : "full";
Use this mode whenever you need a responsive path-traced preview during active painting sessions.

​
Enabling Path Tracing

There are two ways to activate path-traced rendering in ArmorPaint:
1

Switch the viewport display mode

Press Ctrl+M to cycle through viewport modes until VIEWPORT_MODE_PATH_TRACE (mode 15) is selected. This activates the Brute Pathtracer for the current viewport without changing the base render pipeline.
2

Set the render mode to Path Trace

In Preferences, set render_mode to RENDER_MODE_PATH_TRACE (2). This switches the entire rendering pipeline to the path-tracing path so that every viewport frame is dispatched through the ray-tracing backend.
VIEWPORT_MODE_PATH_TRACE and RENDER_MODE_PATH_TRACE are complementary settings. The viewport mode flag controls what the compositor displays; the render mode flag controls which pipeline is used to generate each frame.

​
Scene Limits

The Brute Pathtracer imposes the following hard limits per scene:
LimitValue
Unique objects64
Instances (total)1,024
These limits reflect the acceleration structure capacity of the underlying hardware ray-tracing API. Scenes with more than 64 unique mesh objects or more than 1,024 total instances may not render correctly in path-traced mode.

​
Features by Mode

FeatureFast ModeQuality Mode
Diffuse GI / reflections✅✅
Environment lighting✅✅
Translucency❌✅
Emission❌✅
Sample accumulation (progressive refinement)✅✅

​
Integration with Baking

The same Brute Pathtracer backend powers the ray-traced baking system. When you trigger an AO, Lightmap, Bent Normal, or Thickness bake, the renderer switches into bake mode (render_path_raytrace_is_bake = true), selects the appropriate bake shader, and accumulates ray samples into a set of RGBA64 bake targets: 
// Bake shader selection — render_path_raytrace_bake.c
return g_context->bake_type == BAKE_TYPE_OCCLUSION     ? "raytrace_bake_ao..."
     : g_context->bake_type == BAKE_TYPE_LIGHTMAP      ? "raytrace_bake_light..."
     : g_context->bake_type == BAKE_TYPE_BENT_NORMAL   ? "raytrace_bake_bent..."
     :                                                    "raytrace_bake_thick...";
Bake targets are created at the current project texture resolution (width × height in RGBA64 format). Pixels with an alpha value of 0.0 in the position/normal pre-pass are skipped during ray dispatch, limiting ray budget to visible surface area only. See the Baking page for a full walkthrough of ray-traced bake types and workflow.

​
Environment Map Settings

The path-traced scene uses ArmorPaint’s environment map as the primary light source. Two angular offset parameters let you rotate the lighting without modifying the environment asset itself:
FieldTypeDescription
envmap_anglef32Rotates the environment map around the vertical axis, changing the apparent direction of key lighting in the scene. Default: 0.0.
light_anglef32Independently rotates the dominant light direction within the path-traced scene. Default: 0.0.
The renderer samples the environment map directly during ray tracing. When show_envmap_blur is enabled, the blurred radiance mip chain is used instead of the sharp environment texture, softening reflections and IBL contributions.

​
Environment Sphere Visualization

Three boolean flags on the context control how the environment is displayed in the path-traced and lit viewports:

show_envmap

When true, the environment map is visible as a background sphere in the viewport. When false, the environment still contributes lighting but is hidden from view. The path-traced renderer negates the scene_world->strength value when show_envmap is false to suppress the background.

show_envmap_blur

When true, the blurred (pre-filtered) radiance mip level [0] is used instead of the full-resolution environment texture. This softens the visible background and the reflected environment in shiny surfaces.

show_envmap_spheres

Displays a set of PBR preview spheres in the viewport, each rendered with a different roughness and metallic combination under the current environment lighting. Useful for quickly assessing the full range of PBR response.

​
Performance Recommendations

Use PATHTRACE_MODE_FAST (0) during active painting for a responsive real-time preview. Switch to PATHTRACE_MODE_QUALITY (1) only when you need to evaluate translucency or emission, or when triggering ray-traced bake operations that require the full feature set. The difference in shader complexity between core and full mode has a measurable impact on ray dispatch time, especially in scenes with many instances.
For developers interested in the Brute Pathtracer internals, the shader source lives in the base/shaders/raytrace/src/ directory of the ArmorPaint repository. The C-side path-tracing runtime is implemented in:
  • base/sources/render_path_raytrace.c — viewport path-tracing commands and frame accumulation
  • base/sources/render_path_raytrace_bake.c — ray-traced baking dispatch and target management
  • base/sources/iron_gpu.h — GPU abstraction layer for DXR / Vulkan RT / Metal RT

Build docs developers (and LLMs) love

Get started for freeTalk to us