Diagnosing Love2D Canvas Rendering Issues: Blur, Offset, Alpha, and Size Limits

Recognizable Condition

When using Love2D canvases (render‑to‑texture) you may notice one of the following symptoms:

• The canvas looks blurry or pixelated when drawn to the screen.
• Content drawn from the canvas appears shifted or offset.
• Edges of the canvas look dark or have incorrect alpha.
• The canvas shows a blank screen on certain platforms (e.g., Android).

Cause and Diagnostic Overview

Condition	Likely Cause	Quick Diagnostic Check
Blurry/pixelated output	Canvas filter mode left at default linear when the canvas size is not an integer multiple of the window size.	Call love.graphics.getFilter() on the canvas; if it returns 'linear' and canvas:getWidth() % windowWidth ~= 0 (or similar for height), blurriness is expected.
Shifted/offset drawing	Viewport or scissor left active from a previous canvas render.	Record love.graphics.getViewport() before and after drawing to the canvas; differing values indicate a viewport mismatch.
Dark edges / incorrect alpha	Blend mode not suited for the canvas (e.g., using 'alpha' when the canvas was cleared with premultiplied alpha) or not clearing the canvas properly.	Check love.graphics.getBlendMode(); if it does not match the clearing mode used (love.graphics.clear(r,g,b,a)), alpha issues may appear.
Blank canvas on Android	Canvas dimensions exceed the device’s maximum texture size.	Query love.graphics.getSystemLimits() (or love.graphics.getLimits() in older builds) and compare the requested canvas width/height to the reported maxTextureSize.

Ordered Checks

1. Verify the canvas filter mode and size relationship.
2. Confirm viewport and scissor state after each canvas render.
3. Inspect the current blend mode and how the canvas was cleared.
4. On mobile targets, check the reported maximum texture size against your canvas dimensions.

Fixes Tied to Findings

Fix for Blurry Output

Set the canvas filter to nearest (or another mode that matches your scaling intent) before drawing the canvas to the screen.

-- Create canvas
local myCanvas = love.graphics.newCanvas(400, 300)
-- Use nearest filter to avoid interpolation blur
myCanvas:setFilter('nearest', 'nearest')
-- ... render to canvas ...
-- Draw canvas to window (may be scaled)
love.graphics.draw(myCanvas, 0, 0, 0, 2, 2)  -- example 2x scaling

If you need linear filtering for smooth scaling, ensure the canvas dimensions are integer multiples of the final draw scale (e.g., canvas 200x150 drawn at 2x gives 400x300).

Fix for Viewport/Scissor Offset

After finishing canvas rendering, reset the viewport and scissor to the window’s full size.

love.graphics.setCanvas(myCanvas)
-- draw to canvas
love.graphics.setCanvas()
-- reset viewport/scissor
love.graphics.setViewport(0, 0, love.graphics.getWidth(), love.graphics.getHeight())
love.graphics.setScissor()
-- now draw UI or other elements

Fix for Alpha/Blend Mode Issues

Match the blend mode to how you clear the canvas, or explicitly set the blend mode before drawing the canvas.

-- Clear canvas with premultiplied alpha
love.graphics.setCanvas(myCanvas)
love.graphics.clear(0, 0, 0, 0)  -- transparent premultiplied
love.graphics.setCanvas()
-- Use premultiplied blend mode when drawing
love.graphics.setBlendMode('premultiplied', 'alphamultiply')
love.graphics.draw(myCanvas, 0, 0)
-- Restore default blend mode afterwards
love.graphics.setBlendMode('alpha', 'alphamultiply')

Fix for Texture‑Size Limit on Android

Reduce the canvas size to stay within the device’s limit, or create multiple smaller canvases and combine them.

local limits = love.graphics.getSystemLimits()
local maxSize = limits.maxTextureSize
local canvasW, canvasH = 800, 600
if canvasW > maxSize or canvasH > maxSize then
    -- scale down or split
    canvasW = math.min(canvasW, maxSize)
    canvasH = math.min(canvasH, maxSize)
end
local myCanvas = love.graphics.newCanvas(canvasW, canvasH)

Escalation Criteria

• If adjusting filter, viewport, blend mode, and canvas size does not resolve the issue, verify that you are not inadvertently changing global state elsewhere in your code (e.g., a library that alters love.graphics.setFilter globally).
• On Android, if the reported maxTextureSize seems incorrect for a known device, test on a different device or use love.graphics.getLimits() as a fallback and log the values.
• When the problem persists across multiple symptom types, consider creating a minimal reproducible example (MRE) that isolates canvas creation, rendering, and drawing to verify whether the issue lies in your game logic or the Love2D build.