# How Viewport Modes Affect Texture Painting Display in ArmorPaint

> Discover how ArmorPaint viewport modes enhance texture painting by visualizing material, UV layout, masks, and normals for instant artist feedback.

- Repository: [Armory 3D/armorpaint](https://github.com/armory3d/armorpaint)
- Tags: how-to-guide
- Published: 2026-09-11

---

**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.

```typescript
// 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`](https://github.com/armory3d/armorpaint/blob/main/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`](https://github.com/armory3d/armorpaint/blob/main/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`](https://github.com/armory3d/armorpaint/blob/main/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.