How Viewport Modes Affect Texture Painting Display in ArmorPaint

Viewport modes in ArmorPaint switch the active shader and rendering pipeline to visualize different texture channels—such as material, UV layout, masks, or normals—giving artists immediate visual feedback while painting.

ArmorPaint is an open-source 3D texture painting application developed by the Armory3D team. Understanding how viewport modes affect texture painting display helps you toggle between material previews, UV validation, and mask overlays without interrupting your workflow.

How Viewport Modes Alter Texture Painting Visualization

ArmorPaint provides dedicated viewport modes that change the GPU shader program used to render the mesh. Each mode disables irrelevant visual data and highlights specific texture channels.

Material Preview Mode

Material mode is the default view for texture painting. It renders the mesh using the full material preview shader (src/shaders/MaterialPreview.hx), displaying albedo, roughness, metalness, and normal data combined. Use this mode for general texture authoring to verify how colors and surface properties will appear in-game.

UV Layout Mode

UV mode visualizes the mesh's UV coordinates directly on the surface, typically rendered as a red-green gradient grid. The material shader is completely disabled, and the uniform u_showUV is enabled in src/shaders/UVViz.hx. This mode is essential for checking seam alignment, texel density, and UV distortion while painting.

Mask and Stencil Modes

Mask mode displays only the black-and-white mask texture channel that controls where paint is applied. Stencil mode shows the stencil channel as a translucent overlay for layer-based masking. Both modes use src/shaders/MaskViz.hx to isolate these channels, allowing you to paint opacity and hardness maps with precision.

Normal Map Visualization

Normal mode renders the normal map using a dedicated visualization shader (src/shaders/NormalViz.hx) that encodes surface direction as RGB colors. This helps debug normal map orientation and fix shading artifacts before exporting assets.

Packed Texture Mode

Packed mode displays combined RGBA textures where each channel stores a different map (e.g., roughness in red, metallic in green). This mode verifies that packed channels align correctly before engine export.

Source Code Implementation of Viewport Modes

The viewport mode system is implemented across the renderer core, shader compilation units, and UI toolbar.

Viewport State Management (src/renderer/Viewport.hx)

The Viewport class in src/renderer/Viewport.hx maintains the current rendering state. When you select a mode, the method Viewport.setMode(mode) updates the active shader program and triggers a redraw. The class stores references to compiled shader objects for each visualization type.

Shader Selection Logic

Under the hood, setMode() executes a switch statement that binds the appropriate GPU program. The renderer updates uniform flags—such as disabling lighting calculations for UV mode or enabling mask sampling for Mask mode—before issuing the draw call.

// Example of the shader switch (simplified)
function setMode(mode: ViewportMode) {
    switch (mode) {
        case ViewportMode.Material:
            shader = shaders.materialPreview;
            break;
        case ViewportMode.UV:
            shader = shaders.uvViz;
            break;
        case ViewportMode.Mask:
            shader = shaders.maskViz;
            break;
        // …other cases…
    }
    renderer.useShader(shader);
    renderer.drawMesh(currentMesh);
}

UI Toolbar Integration (src/ui/ToolbarViewMode.ts)

The mode selection interface lives in src/ui/ToolbarViewMode.ts. Clicking a toolbar button invokes Viewport.setMode(ViewportMode.UV) (or the respective mode), ensuring the 3D view updates instantly. This separation of UI and renderer logic keeps the painting canvas responsive during mode switches.

Practical Usage During Painting

Switch viewport modes based on your current validation needs:

• While painting base colors: Stay in Material mode to see immediate PBR results.
• While fixing seams: Switch to UV mode to verify coordinate mapping.
• While creating layer masks: Toggle Mask mode to see exactly where your brush will affect the surface.
• Before export: Use Packed mode to confirm channel packing aligns with your game engine's expectations.

Summary

• ArmorPaint viewport modes switch the underlying GPU shader to visualize specific texture data.
• Material mode uses src/shaders/MaterialPreview.hx for full PBR preview.
• UV, Mask, and Normal modes use dedicated shaders (UVViz.hx, MaskViz.hx, NormalViz.hx) to isolate technical channels.
• The Viewport class in src/renderer/Viewport.hx manages state via setMode(), while src/ui/ToolbarViewMode.ts provides the interface controls.
• Changing modes updates uniform flags and redraws the mesh instantly.

Frequently Asked Questions

How do I switch viewport modes in ArmorPaint?

Click the mode buttons in the viewport toolbar (implemented in src/ui/ToolbarViewMode.ts), or programmatically call Viewport.setMode(ViewportMode.Material) using the mode enum defined in the ArmorPaint API. The change applies immediately without requiring a scene reload.

Why does UV mode disable material lighting?

UV visualization requires a specialized shader (src/shaders/UVViz.hx) that outputs coordinate data as color values. Lighting calculations would obscure the UV grid, so the shader sets u_showUV to true and skips all PBR lighting uniforms to provide a clear, unshaded view of the texture layout.

What is the difference between Mask mode and Stencil mode?

Mask mode displays the active paint mask as a black-and-white texture controlling brush application areas. Stencil mode shows the stencil channel used for layer compositing, typically rendered as a translucent overlay. Both use src/shaders/MaskViz.hx but sample different texture inputs to help you validate opacity versus layer selection.

Which mode should I use to verify exported textures?

Use Packed mode to verify that multiple texture maps (roughness, metallic, ambient occlusion) are correctly packed into individual RGBA channels before export. This mode renders the packed texture directly, ensuring channel alignment matches your target game engine's specifications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}