SetNextWindowCached(key): opt-in cached windows on top of the refresh policy (skip contents while idle), t_cached_window test, README snippet

build/ImGui.linemap.json

@@ -1 +1 @@
-[[12, "imgui.lua"], [18472, "imgui_demo.lua"], [25757, "imgui_draw.lua"], [30995, "imgui_h.lua"], [33193, "imgui_impl_roblox.lua"], [34525, "imgui_impl_roblox_fonts.lua"], [40928, "imgui_internal.lua"], [44100, "imgui_tables.lua"], [48447, "imgui_widgets.lua"], [58202, "imstb_rectpack.lua"], [58648, "imstb_textedit.lua"], [59889, "imstb_truetype.lua"], [62357, "imstd_minstdio.lua"]]
+[[12, "imgui.lua"], [18510, "imgui_demo.lua"], [25795, "imgui_draw.lua"], [31033, "imgui_h.lua"], [33231, "imgui_impl_roblox.lua"], [34563, "imgui_impl_roblox_fonts.lua"], [40966, "imgui_internal.lua"], [44142, "imgui_tables.lua"], [48489, "imgui_widgets.lua"], [58244, "imstb_rectpack.lua"], [58690, "imstb_textedit.lua"], [59931, "imstb_truetype.lua"], [62399, "imstd_minstdio.lua"]]

build/ImGui.luau

@@ -8857,6 +8857,26 @@ function ImGui.UpdateWindowSkipRefresh(window)
     end
 
     if bit32.band(g.NextWindowData.RefreshFlagsVal, ImGuiWindowRefreshFlags.TryToAvoidRefresh) ~= 0 then
+        -- [Port] SetNextWindowCached(): refresh on any change since the last refresh (and one frame after being busy)
+        if g.NextWindowData.CacheKeySet then
+            local function related(w) return w ~= nil and (w.RootWindow == window.RootWindow or ImGui.IsWindowWithinBeginStackOf(w.RootWindow, window)) end
+            local busy = window.Appearing or window.Hidden or window.DockIsActive or related(g.HoveredWindow) or related(g.NavWindow) or related(g.ActiveIdWindow) or (g.MovingWindow ~= nil and related(g.MovingWindow))
+            local c, key, ds, tex = window.CacheSnap, g.NextWindowData.CacheKeyVal, g.IO.DisplaySize, g.IO.Fonts.TexData
+            if busy or c == nil or c.Busy or c.Key ~= key or c.Tex ~= tex or c.Collapsed ~= window.Collapsed
+                or c.PosX ~= window.Pos.x or c.PosY ~= window.Pos.y or c.SizeX ~= window.SizeFull.x or c.SizeY ~= window.SizeFull.y
+                or c.ScrollX ~= window.Scroll.x or c.ScrollY ~= window.Scroll.y or window.ScrollTarget.x < FLT_MAX or window.ScrollTarget.y < FLT_MAX
+                or c.DisplayX ~= ds.x or c.DisplayY ~= ds.y then
+                c = c or {}
+                window.CacheSnap = c
+                c.Busy, c.Key, c.Tex, c.Collapsed = busy, key, tex, window.Collapsed
+                c.PosX, c.PosY, c.SizeX, c.SizeY = window.Pos.x, window.Pos.y, window.SizeFull.x, window.SizeFull.y
+                c.ScrollX, c.ScrollY, c.DisplayX, c.DisplayY = window.Scroll.x, window.Scroll.y, ds.x, ds.y
+                return
+            end
+            -- skip: widgets early-out on SkipItems and Begin() returns visible=false; End() restores it
+            window.CacheSkipItemsBackup = window.SkipItems
+            window.SkipItems = true
+        end
         -- FIXME-IDLE: Tests for e.g. mouse clicks or keyboard while focused.
         if window.Appearing then  -- If currently appearing
             return
@@ -9488,6 +9508,20 @@ function ImGui.SetNextWindowRefreshPolicy(flags)
     local g = GImGui
     g.NextWindowData.HasFlags = bit32.bor(g.NextWindowData.HasFlags, ImGuiNextWindowDataFlags.HasRefreshPolicy)
     g.NextWindowData.RefreshFlagsVal = flags
+    g.NextWindowData.CacheKeySet = false
+end
+
+-- [Port] Opt-in cached window (built on the refresh policy above). While nothing that could change the window
+-- happened, Begin() keeps last frame's draw list and returns visible=false, so `if visible then ... end` skips your code.
+-- It refreshes when `key` changes (pass e.g. a version number of the data shown), while the window (or a popup/child
+-- of it) is hovered, focused or active and for one frame after, and when it appears, moves, resizes, scrolls,
+-- collapses, is docked, or the display size or font atlas texture changes.
+-- Anything else that changes the contents (style, fonts, time) must be part of `key`.
+function ImGui.SetNextWindowCached(key)
+    local g = GImGui
+    ImGui.SetNextWindowRefreshPolicy(bit32.bor(ImGuiWindowRefreshFlags.TryToAvoidRefresh, ImGuiWindowRefreshFlags.RefreshOnHover, ImGuiWindowRefreshFlags.RefreshOnFocus))
+    g.NextWindowData.CacheKeySet = true
+    g.NextWindowData.CacheKeyVal = key
 end
 
 function ImGui.GetWindowDpiScale()
@@ -10690,6 +10724,10 @@ function ImGui.End()
         IM_ASSERT(window.DrawList == nil)
         window.DrawList = window.DrawListInst
     end
+    if window.CacheSkipItemsBackup ~= nil then -- [Port] SetNextWindowCached()
+        window.SkipItems = window.CacheSkipItemsBackup
+        window.CacheSkipItemsBackup = nil
+    end
 
     -- Stop logging
     if g.LogWindow == window then -- FIXME: add more options for scope of logging
@@ -42163,7 +42201,9 @@ function ImGuiNextWindowData()
         SizeCallbackUserData = nil,
         BgAlphaVal           = nil,
         MenuBarOffsetMinVal  = ImVec2(),
-        RefreshFlagsVal      = nil
+        RefreshFlagsVal      = nil,
+        CacheKeySet          = false, -- [Port] SetNextWindowCached()
+        CacheKeyVal          = nil
     }, IMGUI_NEXT_WINDOW_DATA)
 end
 
@@ -43335,6 +43375,8 @@ function ImGuiWindow(ctx, name)
         SkipItems = false,
 
         SkipRefresh = false,
+        CacheSnap = nil, -- [Port] SetNextWindowCached(): state at the last refresh
+        CacheSkipItemsBackup = nil,
 
         Appearing = false,
 

build/ImGuiTyped.luau

@@ -516,7 +516,7 @@ export type ImGuiAPI = {
     NavUpdateWindowingTarget: (...any) -> ...any,
     NewFrame: () -> (),
     NewLine: () -> (),
-    NewTextBuffer: (...any) -> ...any,
+    NewTextBuffer: (str: string, size: number?) -> {number},
     NextColumn: () -> (),
     OpenPopup: (...any) -> ...any,
     OpenPopupEx: (...any) -> ...any,
@@ -643,6 +643,7 @@ export type ImGuiAPI = {
     SetNextItemStorageID: (storage_id: number) -> (),
     SetNextItemWidth: (item_width: number) -> (),
     SetNextWindowBgAlpha: (alpha: number) -> (),
+    SetNextWindowCached: (key: any) -> (),
     SetNextWindowChildFlags: (...any) -> ...any,
     SetNextWindowClass: (window_class: any) -> (),
     SetNextWindowCollapsed: (collapsed: boolean, cond: number?) -> (),
@@ -823,7 +824,7 @@ export type ImGuiAPI = {
     TestKeyOwner: (...any) -> ...any,
     Text: (fmt: string, ...any) -> (),
     TextAligned: (...any) -> ...any,
-    TextBufferToString: (...any) -> ...any,
+    TextBufferToString: (buf: {number}) -> string,
     TextColored: (col: ImVec4, fmt: string, ...any) -> (),
     TextDisabled: (fmt: string, ...any) -> (),
     TextEx: (...any) -> ...any,

build/imgui_love.linemap.json

@@ -1 +1 @@
-[[149, "imgui.lua"], [18609, "imgui_demo.lua"], [25894, "imgui_draw.lua"], [31132, "imgui_h.lua"], [33330, "imgui_impl_love.lua"], [33870, "imgui_internal.lua"], [37042, "imgui_tables.lua"], [41389, "imgui_widgets.lua"], [51144, "imstb_rectpack.lua"], [51590, "imstb_textedit.lua"], [52831, "imstb_truetype.lua"], [55299, "imstd_minstdio.lua"]]
+[[149, "imgui.lua"], [18647, "imgui_demo.lua"], [25932, "imgui_draw.lua"], [31170, "imgui_h.lua"], [33368, "imgui_impl_love.lua"], [33908, "imgui_internal.lua"], [37084, "imgui_tables.lua"], [41431, "imgui_widgets.lua"], [51186, "imstb_rectpack.lua"], [51632, "imstb_textedit.lua"], [52873, "imstb_truetype.lua"], [55341, "imstd_minstdio.lua"]]

build/imgui_love.lua

@@ -8994,6 +8994,26 @@ function ImGui.UpdateWindowSkipRefresh(window)
     end
 
     if bit32.band(g.NextWindowData.RefreshFlagsVal, ImGuiWindowRefreshFlags.TryToAvoidRefresh) ~= 0 then
+        -- [Port] SetNextWindowCached(): refresh on any change since the last refresh (and one frame after being busy)
+        if g.NextWindowData.CacheKeySet then
+            local function related(w) return w ~= nil and (w.RootWindow == window.RootWindow or ImGui.IsWindowWithinBeginStackOf(w.RootWindow, window)) end
+            local busy = window.Appearing or window.Hidden or window.DockIsActive or related(g.HoveredWindow) or related(g.NavWindow) or related(g.ActiveIdWindow) or (g.MovingWindow ~= nil and related(g.MovingWindow))
+            local c, key, ds, tex = window.CacheSnap, g.NextWindowData.CacheKeyVal, g.IO.DisplaySize, g.IO.Fonts.TexData
+            if busy or c == nil or c.Busy or c.Key ~= key or c.Tex ~= tex or c.Collapsed ~= window.Collapsed
+                or c.PosX ~= window.Pos.x or c.PosY ~= window.Pos.y or c.SizeX ~= window.SizeFull.x or c.SizeY ~= window.SizeFull.y
+                or c.ScrollX ~= window.Scroll.x or c.ScrollY ~= window.Scroll.y or window.ScrollTarget.x < FLT_MAX or window.ScrollTarget.y < FLT_MAX
+                or c.DisplayX ~= ds.x or c.DisplayY ~= ds.y then
+                c = c or {}
+                window.CacheSnap = c
+                c.Busy, c.Key, c.Tex, c.Collapsed = busy, key, tex, window.Collapsed
+                c.PosX, c.PosY, c.SizeX, c.SizeY = window.Pos.x, window.Pos.y, window.SizeFull.x, window.SizeFull.y
+                c.ScrollX, c.ScrollY, c.DisplayX, c.DisplayY = window.Scroll.x, window.Scroll.y, ds.x, ds.y
+                return
+            end
+            -- skip: widgets early-out on SkipItems and Begin() returns visible=false; End() restores it
+            window.CacheSkipItemsBackup = window.SkipItems
+            window.SkipItems = true
+        end
         -- FIXME-IDLE: Tests for e.g. mouse clicks or keyboard while focused.
         if window.Appearing then  -- If currently appearing
             return
@@ -9625,6 +9645,20 @@ function ImGui.SetNextWindowRefreshPolicy(flags)
     local g = GImGui
     g.NextWindowData.HasFlags = bit32.bor(g.NextWindowData.HasFlags, ImGuiNextWindowDataFlags.HasRefreshPolicy)
     g.NextWindowData.RefreshFlagsVal = flags
+    g.NextWindowData.CacheKeySet = false
+end
+
+-- [Port] Opt-in cached window (built on the refresh policy above). While nothing that could change the window
+-- happened, Begin() keeps last frame's draw list and returns visible=false, so `if visible then ... end` skips your code.
+-- It refreshes when `key` changes (pass e.g. a version number of the data shown), while the window (or a popup/child
+-- of it) is hovered, focused or active and for one frame after, and when it appears, moves, resizes, scrolls,
+-- collapses, is docked, or the display size or font atlas texture changes.
+-- Anything else that changes the contents (style, fonts, time) must be part of `key`.
+function ImGui.SetNextWindowCached(key)
+    local g = GImGui
+    ImGui.SetNextWindowRefreshPolicy(bit32.bor(ImGuiWindowRefreshFlags.TryToAvoidRefresh, ImGuiWindowRefreshFlags.RefreshOnHover, ImGuiWindowRefreshFlags.RefreshOnFocus))
+    g.NextWindowData.CacheKeySet = true
+    g.NextWindowData.CacheKeyVal = key
 end
 
 function ImGui.GetWindowDpiScale()
@@ -10827,6 +10861,10 @@ function ImGui.End()
         IM_ASSERT(window.DrawList == nil)
         window.DrawList = window.DrawListInst
     end
+    if window.CacheSkipItemsBackup ~= nil then -- [Port] SetNextWindowCached()
+        window.SkipItems = window.CacheSkipItemsBackup
+        window.CacheSkipItemsBackup = nil
+    end
 
     -- Stop logging
     if g.LogWindow == window then -- FIXME: add more options for scope of logging
@@ -35105,7 +35143,9 @@ function ImGuiNextWindowData()
         SizeCallbackUserData = nil,
         BgAlphaVal           = nil,
         MenuBarOffsetMinVal  = ImVec2(),
-        RefreshFlagsVal      = nil
+        RefreshFlagsVal      = nil,
+        CacheKeySet          = false, -- [Port] SetNextWindowCached()
+        CacheKeyVal          = nil
     }, IMGUI_NEXT_WINDOW_DATA)
 end
 
@@ -36277,6 +36317,8 @@ function ImGuiWindow(ctx, name)
         SkipItems = false,
 
         SkipRefresh = false,
+        CacheSnap = nil, -- [Port] SetNextWindowCached(): state at the last refresh
+        CacheSkipItemsBackup = nil,
 
         Appearing = false,