ArmorPaint Color Blending Modes: Complete Guide to Layer Compositing

ArmorPaint implements ten Porter-Duff style color blending modes—including Replace, Multiply, Add, Overlay, and Screen—that control how texture layers composite via the layer.blend_mode property and underlying WGPUBlendFactor mappings.

ArmorPaint provides a robust set of color blending modes for layer-based texture painting, enabling artists to control precisely how each layer interacts with those beneath it. These modes map directly to GPU blend factors in the WebGPU backend, ensuring real-time performance. The implementation spans the rendering pipeline from FBX import parsing to shader execution.

How ArmorPaint Translates Blend Modes to the GPU

At the core of the blending system lies the id_to_blend_factor function defined in base/sources/backends/data/wasm/start.js (lines 161-598). This utility converts internal integer identifiers into WGPUBlendFactor enumerations used by the graphics API for both color and alpha channel operations.

When importing assets, the FBX parser extracts per-layer blend specifications via the ufbx_blend_mode enum around line 20785 of paint/plugins/io_fbx/ufbx/ufbx.c. These imported values flow through the same mapping function, ensuring consistency between imported scenes and manually configured layers.

Complete List of ArmorPaint Color Blending Modes

ArmorPaint exposes ten distinct blending algorithms through the layer properties UI and scripting interface:

• Replace / Normal: Source color completely overwrites the destination with no mathematical blending.
• Multiply: Multiplies source and destination colors, darkening the result—ideal for shadow painting.
• Add: Adds source values to destination values, creating lightening effects suitable for glows.
• Subtract: Subtracts source color from destination color, inverting brightness relationships.
• Overlay: Combines Multiply and Screen operations, preserving highlights and shadows while enhancing contrast.
• Screen: Inverts both colors, multiplies them, then inverts the result—producing lighter outputs than Multiply.
• Soft Light: Applies a gentler version of Overlay, yielding subtle lighting effects without harsh transitions.
• Hard Light: Uses the source layer as a harsh light source, producing high-contrast results similar to Overlay but with more intensity.
• Linear Dodge (Add): Performs addition without color clamping, supporting HDR workflows where values exceed 1.0.
• Linear Burn (Subtract): Executes subtraction without clamping, allowing for extreme darkening beyond standard color ranges.

Programmatic Control of Blend Modes

You can manipulate blending modes dynamically through ArmorPaint's JavaScript scripting interface using the layer.blend_mode property.

Set an existing layer's mode:

const layer = project.layers[2];
layer.blend_mode = 'Multiply';
project.update();

Read the current mode of the active layer:

const active = project.active_layer;
console.log(`Current blend mode: ${active.blend_mode}`);

Create a new layer with a specific blending mode:

const newLayer = project.add_layer('HighlightLayer');
newLayer.blend_mode = 'Overlay';
project.update();

Source Code Architecture

The blending pipeline spans three critical locations in the armory3d/armorpaint repository:

• paint/plugins/io_fbx/ufbx/ufbx.c (line 20785): Defines the ufbx_blend_mode enum that translates FBX-encoded blend specifications into internal integer IDs during asset import.
• base/sources/backends/data/wasm/start.js (lines 161-598): Implements the id_to_blend_factor conversion logic that maps these IDs to WebGPU blend factors for runtime rendering.
• paint/shaders/*.kong (e.g., layer_merge.kong): Contains the shader programs that execute the actual color mathematics on the GPU based on the selected mode.

Summary

• ArmorPaint provides ten Porter-Duff style blend modes ranging from basic Replace to advanced Linear Burn.
• The system bridges FBX import data through ufbx_blend_mode to runtime WGPUBlendFactor mappings via id_to_blend_factor.
• Artists can access these modes through the UI or programmatically via layer.blend_mode in JavaScript.
• Implementation spans the import parser (ufbx.c), backend conversion (start.js), and GPU shaders (.kong files).

Frequently Asked Questions

What color blending modes are available in ArmorPaint?

ArmorPaint supports ten blend modes: Replace/Normal, Multiply, Add, Subtract, Overlay, Screen, Soft Light, Hard Light, Linear Dodge (Add), and Linear Burn (Subtract). These cover standard darkening, lightening, contrast, and HDR operations.

How does ArmorPaint handle blend modes from imported FBX files?

During FBX import, the parser reads the per-layer BlendMode enum into the ufbx_blend_mode field in paint/plugins/io_fbx/ufbx/ufbx.c. These values pass through the id_to_blend_factor function in base/sources/backends/data/wasm/start.js to ensure imported blend settings match ArmorPaint's internal rendering pipeline.

Can I change blend modes via scripting in ArmorPaint?

Yes. Access any layer's blend_mode property in JavaScript using strings like 'Multiply' or 'Overlay'. Changes take effect after calling project.update().

Where is the blending logic implemented in the ArmorPaint source code?

The color blending implementation spans three layers: the FBX parser (ufbx.c) handles import encoding, the WebGPU backend (start.js) converts IDs to GPU blend factors, and the shader files (layer_merge.kong) execute the final color mathematics on the GPU.

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