blur perf warning

modules/Blur.lua

@@ -1,6 +1,9 @@
 -- Lua 5.2+ compatibility for unpack
 local unpack = table.unpack or unpack
 
+-- Warning cache to prevent duplicate warnings for the same element
+local warningCache = {}
+
 local Cache = {
   canvases = {},
   quads = {},
@@ -10,6 +13,7 @@ local Cache = {
   MAX_QUAD_SIZE = 20,
   MAX_BLURRED_CANVAS_CACHE = 50, -- Maximum cached blurred canvases
   INTENSITY_THRESHOLD = 5, -- Skip blur below this intensity
+  LARGE_BLUR_THRESHOLD = 250 * 250, -- Warn if blur area exceeds this (250x250px)
 }
 
 --- Round canvas size to nearest bucket for better reuse
@@ -210,6 +214,7 @@ function Cache.clear()
   Cache.quads = {}
   Cache.blurInstances = {}
   Cache.blurredCanvases = {}
+  warningCache = {} -- Clear warning cache on cache clear
 end
 
 -- ============================================================================
@@ -309,6 +314,50 @@ end
 local Blur = {}
 Blur.__index = Blur
 
+--- Check if we should warn about large blur area in immediate mode
+---@param elementId string|nil Element ID for caching warnings
+---@param width number Blur area width
+---@param height number Blur area height
+---@param blurType string "content" or "backdrop"
+local function checkLargeBlurWarning(elementId, width, height, blurType)
+  -- Skip if no ErrorHandler available
+  if not Blur._ErrorHandler then
+    return
+  end
+
+  -- Skip if not in immediate mode
+  if not Blur._immediateModeOptimizations then
+    return
+  end
+
+  -- Calculate blur area
+  local area = width * height
+
+  -- Skip if area is below threshold
+  if area <= Cache.LARGE_BLUR_THRESHOLD then
+    return
+  end
+
+  -- Generate warning key (use elementId if available, otherwise use dimensions)
+  local warningKey = elementId or string.format("%dx%d:%s", width, height, blurType)
+
+  -- Skip if already warned for this element/area
+  if warningCache[warningKey] then
+    return
+  end
+
+  -- Mark as warned
+  warningCache[warningKey] = true
+
+  -- Issue warning
+  local message = string.format("Large %s blur area detected (%dx%d = %d pixels) in immediate mode", blurType, width, height, area)
+
+  local suggestion =
+    "Consider using retained mode for this component to avoid recreating blur effects every frame. Large blur operations are expensive and can cause performance issues in immediate mode."
+
+  Blur._ErrorHandler:warn("Blur", "PERF_003", message, suggestion)
+end
+
 --- Create a new blur effect instance
 ---@param props BlurProps? Blur configuration
 ---@return Blur blur The new blur instance
@@ -355,6 +404,9 @@ function Blur:applyToRegion(intensity, x, y, width, height, drawFunc)
     return
   end
 
+  -- Check for large blur area in immediate mode
+  checkLargeBlurWarning(nil, width, height, "content")
+
   intensity = math.max(0, math.min(100, intensity))
 
   -- Intensity 0-100 maps to 0-5 passes
@@ -548,6 +600,9 @@ function Blur:applyBackdropCached(intensity, x, y, width, height, backdropCanvas
     return
   end
 
+  -- Check for large blur area in immediate mode
+  checkLargeBlurWarning(elementId, width, height, "backdrop")
+
   intensity = math.max(0, math.min(100, intensity))
 
   local passes = math.ceil(intensity / 20)

modules/ErrorHandler.lua

@@ -291,6 +291,12 @@ local ErrorCodes = {
       description = "Critical performance threshold exceeded",
       suggestion = "Operation is causing frame drops. Consider optimizing or reducing frequency.",
     },
+    PERF_003 = {
+      code = "FLEXLOVE_PERF_003",
+      category = "PERF",
+      description = "Large blur area in immediate mode",
+      suggestion = "Consider using retained mode for this component to avoid recreating blur effects every frame.",
+    },
 
     -- Memory Warnings (MEM_001 - MEM_099)
     MEM_001 = {