Documentation
Before You Start
Follow these steps to set up your scene correctly before using Light Painter. Skipping these will result in the add-on not working or the paint not being visible in your renders.
Render Properties → Render Engine and set it to Cycles. EEVEE does not support the light texture nodes that this add-on creates. Since the add-on relies heavily on shader computation, it is strongly recommended to set Device to GPU Compute under Render Properties for a significant performance boost — CPU rendering will still work, but GPU will be considerably faster.Add → Light → Spot or Area, and point it at your scene.Light Properties:
• Spot Light — use a small
Radius (e.g. 0.0 – 0.1 m). Keep Spot Size below 160° to reduce distortion and maintain a cleaner projection.
• Area Light — set
Size according to your scene scale (e.g. 5 – 30 m), and keep Spread fairly low (e.g. 0.01 – 0.5).
You can change Radius or Spread later for softer lighting, but while painting, smaller values help you see details clearly.
N key → Lighting tab). Pick your light in the Light dropdown, choose a texture resolution, and click Reset Light to initialize the node setup. Then select the Brush or Gradient tool from the toolbar and start painting!Light Source
Choose which light to paint on and set the base texture resolution.
The Spot or Area light whose texture you want to paint on. Use the eyedropper or dropdown to pick a light from your scene.
Resolution of the light texture (gobo) image that stores your paint. Higher = finer detail, more memory, slower.
Reinitializes the light texture, resets all layers back to a single default one. Use this after changing resolution or if the shader nodes appear broken.
Layers System
A Photoshop-style layer stack for each light. New layers are added at the top. Each layer has its own image, blend mode, opacity, visibility toggle, and transform. Layers are composited from bottom to top.
.exr files to a temp folder on disk — these are required for the layer system to function correctly (undo, persistence, layer compositing). The temp files are cleaned up automatically when the add-on is disabled or Blender is closed. Layer metadata (names, blend modes, order, transforms) is saved inside the .blend file itself.
+ − — adds a new empty layer above the active layer / deletes the active layer.
▲ ▼ — reorder the active layer up (composites later, on top) or down (composites earlier, below).
Duplicate — creates an exact copy of the active layer including image data and all settings. Full
Merge Visible — flattens all visible layers into one; hidden layers are preserved. Full
Active Layer
Controls for the selected (active) layer.
Blend
Master opacity of the layer. At 0 the layer is fully transparent; at 1 it contributes at full strength.
How this layer's pixels combine with the layers below. Standard compositing modes — Mix (alpha-over), Multiply (darken), Screen (lighten), Add (additive light), Subtract (remove light), Overlay (contrast boost), Soft Light (gentle tinting).
Image Tex → Active Layer Full
Pick any image already loaded in Blender. The image will be resized to match the light texture resolution and written into the active layer, replacing its contents.
Fill Color → Active Layer
Fill the active layer with a solid color. Useful for resetting the layer color or adding an initial tint. White = full light, black = no light. Alpha 0 clears the layer entirely. Click Apply to fill.
Layer Transform
Non-destructive transforms on the active layer's image within light UV space.
Offset — translates the layer in UV space (1.0 = full texture width/height).
Rotation — rotates around the pivot point.
Scale — resizes from the pivot (below 1 = enlarge, above 1 = shrink, non-uniform supported).
Pivot — center for rotation/scale in UV space; (0.5, 0.5) = texture center, (0, 0) = bottom-left, range 0–1.
Resets all transform values to defaults.
Hold D + click & drag mouse to move layer Hold F + click & drag mouse to rotate layer Hold V + click & drag mouse to scale layer
Paint Surface Full
Controls which objects receive paint and which should be treated as transparent.
Paint On
Choose which meshes are valid for paint.
Controls the scope of paintable geometry.
Skip Transparent
The add-on does not automatically detect transparent materials. If your scene contains objects that should let light pass through, you must mark them here manually — otherwise the depth pass treats them as solid and they will incorrectly block light and receive paint.
Objects listed here are excluded from both receiving paint and blocking light. They become invisible to the light's depth pass, so light passes through them as if they don't exist.
Paint Mode
Controls the coordinate space and color blending method used during painting. In both modes, you paint through the camera/viewport — the difference is how the paint projects onto the light texture.
In both modes you paint through the camera/viewport view. The difference is how the brush shape is projected onto the light texture:
Camera Space: The paint appears exactly as shown on screen. The brush falloff in the viewport maps 1:1 to the painted result — what you see is what you get. Gradient colors are blended in screen space before being projected onto the light texture. Full
Light Space: Brush stroke calculations (shape, size, and falloff) and gradient blending are performed in light texture space — only the brush center position and the gradient start and end points are taken from the viewport. As a result, the paint may appear distorted in the viewport depending on the light's distance and angle.
The color space in which paint is blended over existing texture pixels. Different spaces produce different midtone hues when mixing. See Color Spaces.
Brush Tool
Switch between painting and erasing.
The color applied by each brush stamp. Disabled when Erase mode is selected.
Radius of the brush circle. In Camera Space the unit is viewport pixels — the brush is exactly the size you see on screen. In Light Space the unit is light texture texels — the brush maps directly to the gobo resolution. Range: 1 – 1024.
Edge sharpness. At 0 the brush fades softly from center to edge. At 1 it has a crisp hard boundary.
Maximum opacity cap per stroke. Even at full flow, the stroke won't exceed this value.
Rate of paint accumulation per stamp. Low values (0.05 – 0.2) build up colour gradually; at 1.0 full colour is applied in a single stamp.
Mathematical curve controlling how opacity transitions from the brush center to its edge.
Gamma correction applied on top of the falloff curve. Below 1 = softer edges, above 1 = harder edges. Range: 0.1 – 2.0
Applies a blur to the brush stroke after each stamp. Smooths out jagged edges and creates softer paint effects.
Measured in light texture texels, not screen pixels. A radius of 1 = 1 pixel in the actual light texture, regardless of viewport zoom.
Shape of the blur kernel. SCurve is fast but may look boxy at large radii. Gaussian stays rounder and smoother.
when Blur is OFF
Prevents painting texels at the edge of the brush stroke footprint to avoid bright halos at the boundary. Most visible effect when painting near the edge of shadow.
How the mouse position is mapped to the light texture when painting in Light Space.
Traces a ray from the camera through the mouse position and hits the scene geometry each frame. Accurate on curved and complex surfaces. When the cursor moves over an area with no geometry (empty space, sky), the add-on automatically falls back to Plane mode until the cursor returns to a surface.
Establishes a paint plane on the first click, then projects all mouse positions onto that plane. Better for complex surfaces as it avoids jitter on noisy or high-poly geometry.
Ctrl+D Clear selection Ctrl+I Invert selection Ctrl+G Move selection
Gradient Tool Full
Click and drag in the viewport to draw a gradient between two points.
Shape of the gradient.
Interpolation curve controlling how colors blend along the gradient.
The space in which the two endpoint colors are interpolated. Different spaces produce different midtone hues. See Color Spaces.
Color at the drag start point. In radial mode this is the center.
Opacity at the start point of the gradient.
Color at the drag end point. In radial mode this is the outer edge.
Opacity at the end point of the gradient.
Swaps start and end colors (and their strengths) with one click. Reverses the gradient without re-dragging. Press X to switch colors during preview
Adds subtle noise/blur to the gradient to reduce banding artifacts, especially visible at lower texture resolutions.
Ctrl+D Clear selection Ctrl+I Invert selection Ctrl+G Move selection
Selection Tool Full
Create a mask that restricts painting — areas outside the selection are protected.
Geometric method to draw the selection.
How a new selection interacts with the existing one.
While making a selection, hold Shift to switch mode to Add, Ctrl to Subtract, or Alt to Intersect with the existing selection.
Removes the mask so all pixels are paintable.
Swaps selected/unselected.
Preview Mode Full
Controls the real-time overlay that displays the painting result directly in the viewport as you paint.
Paint Only — previews only what is currently being drawn, while the rest of the scene renders normally. All Masks — overlays the full light texture and mask over the entire viewport, highlighting unpaintable areas in red, so you can see exactly where the light reaches and where it's blocked.
Raw Color — displays the color exactly as it will be written to the light texture. Light Falloff — shows the real result as it will appear in the scene, including surface normal contribution, distance attenuation, tonemapping, exposure, gamma, and all other factors that define how Blender renders the light.
Enabled by default. When ON, the preview mimics how Blender spreads the light based on the light source's physical size — matching the actual light edge softness you'll see in the final render. Without this, the preview ignores the light source size entirely, so the light texture appear perfectly sharp regardless of how large the light is. The Multiplier (default 1.0) scales the auto-calculated blur amount — above 1 = exaggerated softness, below 1 = sharper than real.
Advanced Settings Full
Defaults work for most scenes — only tweak if you see artifacts.
Light frustum clipping. Increase Far for large scenes; decrease Near if close objects clip.
Offsets paint along normals to prevent shadow acne. Increase if speckled.
Softness — PCF blur (1 = sharp, 5 = soft). Bleed Reduction — VSM power to prevent light leaking through thin objects.
Resolution of internal depth buffers for shadow edges and paint placement. Both default to 2048.
Color Spaces
Defines how colors are blended and interpolated in gradients. The choice affects what the in-between colors look like when mixing two colors together.
Blends colors by rotating through hues, keeping them vivid and saturated in the middle. Great for colorful gradients. Can produce a slight brightness boost at the midpoint.
Blends colors while keeping brightness consistent throughout. Transitions look smooth and even, though the midpoint may appear slightly less saturated.
Mimics how real colored lights mix in the physical world. Accurate and natural, but the midpoint can appear a bit brighter than expected.
A straightforward blend in display color space — the same way most image editors mix colors. Middle colors tend to look darker.
If the embed doesn't load, your browser may block third-party iframes. Use the direct link below instead.
Open Color Space Comparison on Shadertoy