Docs: update Changelog, FAQ, Fonts docs.

docs/CHANGELOG.txt

@@ -39,16 +39,161 @@ HOW TO UPDATE?
  VERSION 1.92.0 WIP (In Progress)
 -----------------------------------------------------------------------
 
+THIS VERSION CONTAINS THE LARGEST AMOUNT OF BREAKING CHANGES SINCE 2015!
+I TRIED REALLY HARD TO KEEP THEM TO A MINIMUM, REDUCE THE AMOUNT OF INTERFERENCES,
+BUT INEVITABLY SOME USERS WILL BE AFFECTED.
+
+IN ORDER TO HELP US IMPROVE THE TRANSITION PROCESS, INCL. DOCUMENTATION AND COMMENTS,
+PLEASE REPORT **ANY** DOUBT, CONFUSION, QUESTIONS, FEEDBACK TO:
+    https://github.com/ocornut/imgui/issues/
+
+As part of the plan to reduce impact of API breaking changes, several unfinished
+changes/features/refactors related to font and text systems and scaling will be
+part of subsequent releases (1.92.1+).
+
+If you are updating from an old version, and expecting a massive or difficult update,
+consider first updating to 1.91.9 to reduce the amount of changes.
+
 Breaking changes:
 
-- TreeNode: renamed ImGuiTreeNodeFlags_NavLeftJumpsBackHere to ImGuiTreeNodeFlags_NavLeftJumpsToParent
-  for clarity. Kept inline redirection enum (will obsolete). (#1079, #8639)
+- Fonts: **IMPORTANT**: if your app was solving the OSX/iOS Retina screen specific
+  logical vs display scale problem by setting io.DisplayFramebufferScale (e.g. to 2.0f)
+  + setting io.FontGlobalScale (e.g. to 1.0f/2.0f) + loading fonts at scaled sizes (e.g. size X * 2.0f):
+  This WILL NOT map correctly to the new system! Because font will rasterize as requested size.
+    - With a legacy backend (< 1.92):
+      - Instead of setting io.FontGlobalScale = 1.0f/N -> set ImFontCfg::RasterizerDensity = N.
+      - This already worked before, but is now pretty much required.
+    - With a new backend (1.92+)
+      - FramebufferScale is automatically used to set current font RasterizerDensity.
+      - FramebufferScale is a per-viewport property provided by backend through the
+        Platform_GetWindowFramebufferScale() handler in 'docking' branch.
+      - So this should be all automatic.
+- Fonts: **IMPORTANT** on Font Sizing:
+   - Before 1.92, fonts were of a single size. They can now be dynamically sized.
+   - PushFont() API now has an optional size parameter. PushFontSize() was also added.
+       void PushFont(ImFont* font) --> void PushFont(ImFont* font, float size = 0.0f);
+   - Before 1.92: ImGui::PushFont() always used font "default" size specified in AddFont() call.
+   - Since  1.92: ImGui::PushFont() preserve the current font size which is a shared value.
+   - To use old behavior:
+     - use 'ImGui::PushFont(font, font->LegacySize)' at call site.
+     - or set 'ImFontConfig::Flags |= ImFontFlags_DefaultToLegacySize' in AddFont() call
+       (not desirable as it requires e.g. third-party code to be aware of it).
+   - ImFont::FontSize was removed and does not make sense anymore.
+     ImFont::LegacySize is the size passed to AddFont().
+   - Renamed/moved 'io.FontGlobalScale' to 'style.FontScaleMain'.
+
+- Textures:
+  - All API functions taking a 'ImTextureID' parameter are now taking a 'ImTextureRef':
+    - ImTextureRef a small composite structure which may be constructed from a ImTextureID.
+      (or constructed from a ImTextureData* which represent a texture which will generally
+      be ready by the time of rendering).
+    - Affected functions are:
+      - ImGui::Image(), ImGui::ImageWithBg(), ImGui::ImageButton(),
+      - ImDrawList::AddImage(), ImDrawList::AddImageQuad(), ImDrawList::AddImageRounded().
+    - We suggest that C users and any higher-level language bindings generators may
+      facilitate converting this in some way, aka emulating the trivial C++ constructor.
+- Fonts: obsoleted ImFontAtlas::GetTexDataAsRGBA32(), GetTexDataAsAlpha8(), Build(), SetTexID()
+  and IsBuilt() functions. The new protocol for backends to handle textures doesn't need them.
+  Kept redirection functions (will obsolete).
+   - A majority of old backends should still work with new code (behaving like they did before).
+   - Calling ImFontAtlas::Build() before initializing new backends will erroneously trigger
+     preloading all glyphs. Will be detected with an assertion after the backend is initialized.
+- Fonts: ImFontConfig::OversampleH/OversampleV default to automatic (== 0)
+  since v1.91.8. It is quite important you keep it automatic until we decide if we want
+  to provide a way to express finer policy, otherwise you will likely waste texture space
+  when using large glyphs. Note that the imgui_freetype backend doesn't use and does not
+  need oversampling.
+- Fonts: specifying glyph ranges is now unnecessary.
+  - The value of ImFontConfig::GlyphRanges[] is only useful for legacy backends.
+  - All GetGlyphRangesXXXX() functions are now marked obsolete:
+    - GetGlyphRangesDefault(), GetGlyphRangesGreek(), GetGlyphRangesKorean(),
+      GetGlyphRangesJapanese(), GetGlyphRangesChineseSimplifiedCommon(),
+      GetGlyphRangesChineseFull(), GetGlyphRangesCyrillic(),
+      GetGlyphRangesThai(), GetGlyphRangesVietnamese().
+- Fonts: removed ImFontAtlas::TexDesiredWidth to enforce a texture width. (#327)
+  (it vaguely made sense with the old system as if unspecified textures width maxed up
+  to 4096 but that limit isn't necessary anymore, and Renderer_TextureMaxWidth covers this)
+  However you may set TexMinWidth = TexMaxWidth for the same effect.
+- Fonts: if you create and manage ImFontAtlas instances yourself (instead of relying on
+  ImGuiContext to create one, you'll need to set the atlas->RendererHasTextures field
+  and call ImFontAtlasUpdateNewFrame() yourself. An assert will trigger if you don't.
+- Fonts: obsolete ImGui::SetWindowFontScale() which is not useful anymore. Prefer using
+  PushFontSize(style.FontSizeBase * factor) or to manipulate other scaling factors.
+- Fonts: obsoleted ImFont::Scale which is not useful anymore.
 - Fonts: changed ImFont::CalcWordWrapPositionA() to ImFont::CalcWordWrapPosition():
-    - old: const char* CalcWordWrapPositionA(float scale, const char* text, ....);
-    - new: const char* CalcWordWrapPosition (float size,  const char* text, ....);
+   - old: const char* CalcWordWrapPositionA(float scale, const char* text, ....);
+   - new: const char* CalcWordWrapPosition (float size,  const char* text, ....);
   The leading 'float scale' parameters was changed to 'float size'.
-  This was necessary as 'scale' is assuming standard font size which is a concept we aim to
-  eliminate in an upcoming update. Kept inline redirection function.
+  This was necessary as 'scale' is assuming a unique font size.
+  Kept inline redirection function assuming using font->LegacySize.
+- Fonts: generally reworked Internals of ImFontAtlas and ImFont.
+  While in theory a vast majority of users shouldn't be affected, some use cases or
+  extensions might be. Among other things:
+    - ImDrawCmd::TextureId has been changed to ImDrawCmd::TexRef.
+    - ImFontAtlas::ConfigData[] has been renamed to ImFontAtlas::Sources[]
+    - ImFont::ConfigData[], ConfigDataCount has been renamed to Sources[], SourceCount.
+    - Each ImFont has a number of ImFontBaked instances corresponding to actively used
+      sizes. ImFont::GetFontBaked(size) retrieves the one for a given size.
+    - Things moved from ImFont to ImFontBaked:
+      - ImFont::IndexAdvanceX[]       -> ImFontBaked::IndexAdvanceX[]
+      - ImFont::Glyphs[]              -> ImFontBaked::Glyphs[]
+      - ImFont::Ascent, Descent       -> ImFontBaked::Ascent, Descent
+      - ImFont::FindGlyph()           -> ImFontBaked::FindGlyph()
+      - ImFont::FindGlyphNoFallback() -> ImFontBaked::FindGlyphNoFallback()
+      - ImFont::GetCharAdvance()      -> ImFontBaked::GetCharAdvance()
+      - Widget code may use ImGui::GetFontBaked() instead of ImGui::GetFont() to
+        access font data for current font at current font size.
+        (and you may use font->GetFontBaked(size) to access it for any other size.)
+            g.Font      == ImGui::GetFont()
+            g.FontSize  == ImGui::GetFontSize()
+            g.FontBaked == ImGui::GetFontBaked() == ImGui::GetFont()->GetFontBaked(ImGui::GetFontSize())
+  Please report if you are affected!
+- Fonts: (users of imgui_freetype)
+  - renamed ImFontAtlas::FontBuilderFlags to ImFontAtlas::FontLoaderFlags.
+  - renamed ImFontConfig::FontBuilderFlags to ImFontConfig::FontLoaderFlags.
+  - renamed ImGuiFreeTypeBuilderFlags to ImGuiFreeTypeLoaderFlags.
+  - if you used runtime imgui_freetype selection rather than the default compile-time
+    option provided by IMGUI_ENABLE_FREETYPE:
+     - renamed/reworked ImFontBuilderIO into ImFontLoader,
+     - renamed ImGuiFreeType::GetBuilderForFreeType() to ImGuiFreeType::GetFontLoader().
+       - old:  io.Fonts->FontBuilderIO = ImGuiFreeType::GetBuilderForFreeType()
+       - new:  io.Fonts.FontLoader = ImGuiFreeType::GetFontLoader()
+- DrawList: Renamed ImDrawList::PushTextureID()/PopTextureID() to PushTexture()/PopTexture().
+- Fonts: (users of custom rectangles)
+  - Renamed AddCustomRectRegular() to AddCustomRect(). (#8466)
+  - Added GetCustomRect() as a replacement for GetCustomRectByIndex() + CalcCustomRectUV(). (#8466)
+  - The output type of GetCustomRect() is now ImFontAtlasRect, which include UV coordinates.
+      - ImFontAtlasCustomRect::X      --> ImFontAtlasRect::x
+      - ImFontAtlasCustomRect::Y      --> ImFontAtlasRect::y
+      - ImFontAtlasCustomRect::Width  --> ImFontAtlasRect::w
+      - ImFontAtlasCustomRect::Height --> ImFontAtlasRect::h
+    Before:
+        const ImFontAtlasCustomRect* r = atlas->GetCustomRectByIndex(custom_rect_id);
+        ImVec2 uv0, uv1;
+        atlas->GetCustomRectUV(r, &uv0, &uv1);
+        ImGui::Image(atlas->TexRef, ImVec2(r->w, r->h), uv0, uv1);
+    After:
+        ImFontAtlasRect r;
+        atlas->GetCustomRect(custom_rect_id, &r);
+        ImGui::Image(atlas->TexRef, ImVec2(r.w, r.h), r.uv0, r.uv1);
+    We added a redirecting typedef but haven't attempted to magically redirect
+    the field names, as this API is rarely used and the fix is simple.
+  - Obsoleted AddCustomRectFontGlyph() as the API does not make sense for scalable fonts:
+    - Kept existing function which uses the font "default size" (Sources[0]->LegacySize).
+    - Added a helper AddCustomRectFontGlyphForSize() which is immediately marked obsolete,
+      but can facilitate transitioning old code.
+    - Prefer adding a font source (ImFontConfig) using a custom/procedural loader.
+- Backends: removed ImGui_ImplXXXX_CreateFontsTexture()/ImGui_ImplXXXX_DestroyFontsTexture()
+  for all backends that had them. They should not be necessary any more.
+   - removed ImGui_ImplMetal_CreateFontsTexture(), ImGui_ImplMetal_DestroyFontsTexture().
+   - removed ImGui_ImplOpenGL2_CreateFontsTexture(), ImGui_ImplOpenGL2_DestroyFontsTexture().
+   - removed ImGui_ImplOpenGL3_CreateFontsTexture(), ImGui_ImplOpenGL3_DestroyFontsTexture().
+   - removed ImGui_ImplSDLGPU3_CreateFontsTexture(), ImGui_ImplSDLGPU3_DestroyFontsTexture().
+   - removed ImGui_ImplSDLRenderer2_CreateFontsTexture(), ImGui_ImplSDLRenderer2_DestroyFontsTexture().
+   - removed ImGui_ImplSDLRenderer3_CreateFontsTexture(), ImGui_ImplSDLRenderer3_DestroyFontsTexture().
+   - removed ImGui_ImplVulkan_CreateFontsTexture(), ImGui_ImplVulkan_DestroyFontsTexture().
+- TreeNode: renamed ImGuiTreeNodeFlags_NavLeftJumpsBackHere to ImGuiTreeNodeFlags_NavLeftJumpsToParent
+  for clarity. Kept inline redirection enum (will obsolete). (#1079, #8639)
 - Commented out PushAllowKeyboardFocus()/PopAllowKeyboardFocus() which was obsoleted
   in 1.89.4 (March 2023). (#3092)
    - PushAllowKeyboardFocus(bool tab_stop) --> PushItemFlag(ImGuiItemFlags_NoTabStop, !tab_stop);
@@ -63,6 +208,89 @@ Breaking changes:
 
 Other changes:
 
+- Textures: added partial texture update protocol. (#8465, #3761)
+  - The Renderer Backend needs to set io.BackendFlags |= ImGuiBackendFlags_RendererHasTextures
+    and handle texture updates requests.
+  - New structs: ImTextureData, ImTextureRect.
+  - New enums: ImTextureStatus, ImTextureFormat.
+  - During its ImGui_ImplXXXX_RenderDrawData() call, the backend can now access a texture list
+    in ImDrawData::Textures[]. Textures may have four distinct states:
+    - ImTextureStatus_WantCreate: requesting backend to create a texture.
+    - ImTextureStatus_WantUpdates: requesting backend to copy given blocks from the CPU side
+       copy of the texture to your graphics pipeline.
+       A 'tex->Updates[]' list of update is provided as well as a single 'tex->UpdatesRect' bounding box.
+    - ImTextureStatus_WantDestroy: requesting backend to destroy the texture.
+       - A 'int UnusedFrames' value is provided to conveniently defer destroying.
+       - Backend is generally free to destroy textures whenever they like.
+    - ImTextureStatus_OK: nothing to do.
+  - Almost all standard backends have been updated to support this.
+  - Backends have allowed to destroy textures at any time if they desire so.
+    A list is available in platform_io.Textures[] for this purpose and for backend shutdown.
+  - Both stb_truetype and FreeType backends have been updated to work with the new
+    system, and they now share more code than before.
+  - Added '#define IMGUI_HAS_TEXTURES' to facilitate compile-time checks for third-party
+    extensions until this is merged with a definitive version number to check.
+- Fonts: font backend/loader may easily be changed dynamically, allowing users to compare
+  rasterizers outputs and features. imgui_freetype is generally beneficial.
+- Fonts: ImFontAtlas::AddFontXXX() functions may be called at any time during the frame.
+- Fonts: ImFontAtlas::AddFontXXX() can fail more gracefully if error handling is configured
+  to not assert (this will be better exposed via future font flags).
+- Fonts: added ImGui::PushFontSize()/PopFontSize() functions.
+- Fonts: added style.FontScaleBase scaling factor (previously called io.FontGlobalScale).
+- Fonts: added style.FontScaleDpi scaling factor. This is designed to be be changed on
+  per-monitor/per-viewport basis, which `io.ConfigDpiScaleFonts` does automatically.
+  (which is why it is separate from FontScaleBase).
+- Fonts: added optional font_size parameter to ImGui::PushFont() function.
+- Fonts: added ImFontAtlas::RemoveFont() function.
+- Fonts: added ImFontAtlas::CompactCache() function.
+- Fonts: added ImFontAtlas::TexDesiredFormat field (default to ImTextureFormat_RGBA32,
+  can be changed to ImTextureFormat_Alpha8).
+- Fonts: added ImFontAtlas::TexMinWidth, TexMinHeight, TexMaxWidth, TexMaxHeight fields.
+- Fonts: added ImFontConfig::PixelSnapV to align scaled GlyphOffset.y to pixel boundaries.
+- Fonts: added ImFontConfig::GlyphExcludeRanges[], which behave similarly to
+  ImFontConfig::GlyphRanges[], but has the opposite meaning. It is tailored to situations
+  where merged fonts have overlapping characters.
+- Fonts: added "Input Glyphs Overlap Detection Tool" which dumps a list of glyphs
+  provided by merged sources, which may help setting up a GlyphExcludeRanges[] filter.
+- Fonts: added ImFontAtlas::FontBackendName (which is surfaced in the "About Dear ImGui"
+  window and other locations).
+- Fonts: added ImFontFlags (currently needs to be passed through ImFontConfig until
+  we revamp font loading API):
+   - ImFontFlags_DefaultToLegacySize: for legacy compatibility: make PushFont() calls
+     without explicit size use font->LegacySize instead of current font size.
+   - ImFontFlags_NoLoadError: disable erroring/assert when calling AddFontXXX()
+     with missing file/data. Calling code is expected to check AddFontXXX() return value.
+   - ImFontFlags_NoLoadGlyphs: disable loading new glyphs.
+   - ImFontFlags_LockBakedSizes: disable loading new baked sizes, disable garbage
+     collecting current ones. e.g. if you want to lock a font to a single size.
+- Fonts: the general design has changed toward meaning that a ImFont doesn't have
+  have a specific size: it may be bound and drawn with any size.
+   - We store ImFontBaked structures internally, which are a cache of information
+     for a given size being drawn. You should not need to deal with ImFontBaked directly.
+   - ImFontBaked structures may be cleaned up between frames when unused, pointers
+     to them are only valid for the current frame.
+   - Added ImFontBaked::IsGlyphLoaded() function.
+- Fonts: custom rect packing has generally been reworked. (#8107, #7962, #1282)
+  - ImFontAtlas::AddCustomRect() (previously AddCustomRectRegular()/AddCustomRectFontGlyph())
+    functions will immediately return a packed rectangle identifier, and you can write your
+    pixels immediately - previously had to wait for Build() to be called.
+    This is also the case when using a legacy backend.
+  - Custom packed rectangles may be moved during a texture change, aka practically anytime.
+    Always refer to latest uvs/position returned by GetCustomRect().
+  - AddCustomRect() returns ImFontAtlasRectId_Invalid on failure.
+  - Added ImFontAtlas::RemoveCustomRect() function.
+  - GetCustomRect() can safely return false and not crash when passed an invalid or removed id.
+- Fonts: texture is now stored in a single format CPU side (save ~25% when using RGBA).
+- Fonts: changing current font to one from a different atlas is supported. (#8080)
+- Fonts: automatic baking of an "..." ellipsis works better with monospace fonts.
+- Fonts: each ImFontConfig font source may provide a custom backend/loader.
+- Fonts: added platform_io.Renderer_TextureMaxWidth/Renderer_TextureMaxHeight fields
+  for Renderer Backend to specify if there is a maximum accepted texture size (not yet used).
+- Fonts: added compile-time overridable '#define ImTextureID_Invalid 0' if you need 0
+  to be a valid low-level texture identifier.
+- Debug Tools: Fonts section: add font preview, add "Remove" button, add "Load all glyphs"
+  button, add selection to change font backend when both are compiled in.
+
 - IO: variations in analog-only components of gamepad events do not interfere
   with trickling of mouse position events (#4921, #8508)
 - Windows: fixed SetNextWindowCollapsed()/SetWindowCollapsed() breaking
@@ -132,39 +360,62 @@ Other changes:
   requires providing a window to the backend. (#8584, #6341)
 - Misc: added extra operators to ImVec4 in IMGUI_DEFINE_MATH_OPERATORS block. (#8510) [@gan74]
 - Demo: changed default framed item width to use Min(GetFontSize() * 12, GetContentRegionAvail().x * 0.40f).
-- Backends: Win32: Fixed an issue where externally losing mouse capture (due to e.g. focus loss)
-  would fail to claim it again the next subsequent click. (#8594)
-- Backends: SDL2, SDL3, OSX: Fill gamepad inputs and set ImGuiBackendFlags_HasGamepad
-  regardless of ImGuiConfigFlags_NavEnableGamepad being set. (#8508)
-- Backends: SDL2, SDL3: don't attempt to call SDL_CaptureMouse() on drivers where we don't
-  call SDL_GetGlobalMouseState(). This is specifically for Wayland but we currently use
-  the same white-list as SDL_GetGlobalMouseState(). (#8561) [@vs49688]
-- Backends: GLFW, SDL2, SDL3: include GLFW/SDL version number in io.BackendPlatformName.
-- Backends: SDL3: Update for SDL3 api changes: revert SDL_GetClipboardText()
-  memory ownership change. (#8530, #7801) [@Green-Sky]
-- Backends: SDL3: honor ImGuiPlatformImeData->WantTextInput as an alternative
-  way to call SDL_StartTextInput(), without IME being necessarily visible. (#8584)
-- Backends: SDLGPU3: Fixed creating atlas texture earlier than other backends, preventing
-  to load fonts between the Init and NewFrames calls.
-- Backends: SDLGPU3: Made ImGui_ImplSDLGPU3_PrepareDrawData() reuse GPU Transfer Buffers which
-  were unusually slow to recreate every frame. Much faster now. (#8534) [@ocornut, @TheMode]
-- Backends: SDLGPU3: added support for ImDrawCallback_ResetRenderState. (#8599)
-- Backends: OpenGL3: made GLES 3.20 contexts not access GL_CONTEXT_PROFILE_MASK nor
-  GL_PRIMITIVE_RESTART. (#8664) [@DyXel]
-- Backends: DirectX10, DirectX11, DirectX12: Honor FramebufferScale to allow for custom
-  platform backends and experiments using it (consistently with other renderer backends,
-  even though in normal condition it is not set under Windows). (#8412) [@WSSDude]
-- Backends: Vulkan: Deep-copy ImGui_ImplVulkan_InitInfo::PipelineRenderingCreateInfo's
-  pColorAttachmentFormats buffer when set, in order to reduce common user-error of
-  specifying a pointer to data that gets out of scope. (#8282)
-- Backends: Vulkan: Load dynamic rendering functions using vkGetDeviceProcAddr()
-  + try both non-KHR and KHR versions. (#8600, #8326, #8365) [@ChrisTom-94]
-- Backends: Vulkan: fixed validation errors in window create/resize helpers used by examples
-  and by multi-viewports implementation, which would typically trigger errors while detaching
-  secondary viewports. (#8600, #8176) [@ChrisTom-94]
-- Examples: Apple+Metal, Apple+OpenGL: add Makefile (CLion opens them nicely). (#8637) [@pthom]
-- Examples: DirectX12+Win32: also test for IsIconic() for sleeping since we don't seem to
-  get a DXGI_STATUS_OCCLUDED signal when minimized. (#8603) [@dooann]
+- Backends:
+  - Backends: DX9/DX10/DX11/DX12, Vulkan, OpenGL2/3, Metal, SDLGPU3, SDLRenderer2/3, Allegro5:
+    - Added ImGuiBackendFlags_RendererHasTextures support. (#8465, #3761, #3471)
+      [@ocornut, @ShironekoBen, @thedmd]
+    - Added ImGui_ImplXXXX_UpdateTexture(ImTextureData* tex) functions for all backend.
+      Available if you want to start uploading textures right after ImGui::Render() and without
+      waiting for the call to ImGui_ImplXXXX_RenderDrawData(). Also useful if you use a staged or
+      multi-threaded rendering schemes, where you might want to set ImDrawData::Textures = NULL. (#8597, #1860)
+  - Backends: GLFW: added ImGui_ImplGlfw_GetContentScaleForMonitor(), ImGui_ImplGlfw_GetContentScaleForWindow()
+    helpers. They are wrappers to glfwGetMonitorContentScale()/glfwGetWindowContentScale(), with compile-time
+    GLFW version checks + returning 1.0f on Apple platform.
+  - Backends: SDL2: added ImGui_ImplSDL2_GetDpiScaleForDisplay() and ImGui_ImplSDL2_GetContentScaleForWindow()
+    helpers. They are wrappers to SDL_GetDisplayDPI(), with compile-time SDL version checks + returning 1.0f
+    on Apple platforms. SDL3 already does this by default.
+  - Backends: Win32: Fixed an issue where externally losing mouse capture (due to e.g. focus loss)
+    would fail to claim it again the next subsequent click. (#8594)
+  - Backends: SDL2, SDL3, OSX: Fill gamepad inputs and set ImGuiBackendFlags_HasGamepad
+    regardless of ImGuiConfigFlags_NavEnableGamepad being set. (#8508)
+  - Backends: SDL2, SDL3: don't attempt to call SDL_CaptureMouse() on drivers where we don't
+    call SDL_GetGlobalMouseState(). This is specifically for Wayland but we currently use
+    the same white-list as SDL_GetGlobalMouseState(). (#8561) [@vs49688]
+  - Backends: GLFW, SDL2, SDL3: include GLFW/SDL version number in io.BackendPlatformName.
+  - Backends: SDL3: Update for SDL3 api changes: revert SDL_GetClipboardText()
+    memory ownership change. (#8530, #7801) [@Green-Sky]
+  - Backends: SDL3: honor ImGuiPlatformImeData->WantTextInput as an alternative
+    way to call SDL_StartTextInput(), without IME being necessarily visible. (#8584)
+  - Backends: SDLGPU3: Fixed creating atlas texture earlier than other backends, preventing
+    to load fonts between the Init and NewFrames calls.
+  - Backends: SDLGPU3: Made ImGui_ImplSDLGPU3_PrepareDrawData() reuse GPU Transfer Buffers which
+    were unusually slow to recreate every frame. Much faster now. (#8534) [@ocornut, @TheMode]
+  - Backends: SDLGPU3: added support for ImDrawCallback_ResetRenderState. (#8599)
+  - Backends: OpenGL3: made GLES 3.20 contexts not access GL_CONTEXT_PROFILE_MASK nor
+    GL_PRIMITIVE_RESTART. (#8664) [@DyXel]
+  - Backends: DirectX10, DirectX11, DirectX12: Honor FramebufferScale to allow for custom
+    platform backends and experiments using it (consistently with other renderer backends,
+    even though in normal condition it is not set under Windows). (#8412) [@WSSDude]
+  - Backends: Vulkan: Deep-copy ImGui_ImplVulkan_InitInfo::PipelineRenderingCreateInfo's
+    pColorAttachmentFormats buffer when set, in order to reduce common user-error of
+    specifying a pointer to data that gets out of scope. (#8282)
+  - Backends: Vulkan: Load dynamic rendering functions using vkGetDeviceProcAddr()
+    + try both non-KHR and KHR versions. (#8600, #8326, #8365) [@ChrisTom-94]
+  - Backends: Vulkan: fixed validation errors in window create/resize helpers used by examples
+    and by multi-viewports implementation, which would typically trigger errors while detaching
+    secondary viewports. (#8600, #8176) [@ChrisTom-94]
+- Examples:
+  - Examples: Made many examples DPI aware by default.
+    The single-viewport is basically:
+     - Query monitor DPI scale. Helpers are provided in some backends.
+     - Call style.ScaleAllSizes() and set style.FontScaleDpi with this factor.
+    Multi-viewport applications may set both of those flags:
+     - io.ConfigDpiScaleFonts = true;
+     - io.ConfigDpiScaleViewports = true;
+    Which will scale fonts but NOT style padding/spacings/thicknesses yet.
+  - Examples: Apple+Metal, Apple+OpenGL: add Makefile (CLion opens them nicely). (#8637) [@pthom]
+  - Examples: DirectX12+Win32: also test for IsIconic() for sleeping since we don't seem to
+    get a DXGI_STATUS_OCCLUDED signal when minimized. (#8603) [@dooann]
 
 
 -----------------------------------------------------------------------

docs/FAQ.md

@@ -24,7 +24,7 @@ or view this file with any Markdown viewer.
 | [I integrated Dear ImGui in my engine and some elements are displaying outside their expected windows boundaries...](#q-i-integrated-dear-imgui-in-my-engine-and-some-elements-are-displaying-outside-their-expected-windows-boundaries) |
 | **Q&A: Usage** |
 | **[About the ID Stack system..<br>Why is my widget not reacting when I click on it?<br>Why is the wrong widget reacting when I click on one?<br>How can I have widgets with an empty label?<br>How can I have multiple widgets with the same label?<br>How can I have multiple windows with the same label?](#q-about-the-id-stack-system)** |
-| [How can I display an image? What is ImTextureID, how does it work?](#q-how-can-i-display-an-image-what-is-imtextureid-how-does-it-work)|
+| [How can I display an image?](#q-how-can-i-display-an-image)<br>[What are ImTextureID/ImTextureRef?](#q-what-are-imtextureidimtextureref)|
 | [How can I use maths operators with ImVec2?](#q-how-can-i-use-maths-operators-with-imvec2) |
 | [How can I use my own maths types instead of ImVec2/ImVec4?](#q-how-can-i-use-my-own-maths-types-instead-of-imvec2imvec4) |
 | [How can I interact with standard C++ types (such as std::string and std::vector)?](#q-how-can-i-interact-with-standard-c-types-such-as-stdstring-and-stdvector) |
@@ -161,7 +161,8 @@ Console SDK also sometimes provide equivalent tooling or wrapper for Synergy-lik
 
 ### Q: I integrated Dear ImGui in my engine and little squares are showing instead of text...
 Your renderer backend is not using the font texture correctly or it hasn't been uploaded to the GPU.
-- If this happens using the standard backends: A) have you modified the font atlas after `ImGui_ImplXXX_NewFrame()`? B) maybe the texture failed to upload, which **can if your texture atlas is too big**. Also see [docs/FONTS.md](https://github.com/ocornut/imgui/blob/master/docs/FONTS.md).
+- If this happens using standard backends (before 1.92): A) have you modified the font atlas after `ImGui_ImplXXX_NewFrame()`? B) maybe the texture failed to upload, which **can if your texture atlas is too big**. Also see [docs/FONTS.md](https://github.com/ocornut/imgui/blob/master/docs/FONTS.md).
+- If this happens using standard backends (after 1.92): please report.
 - If this happens with a custom backend: make sure you have uploaded the font texture to the GPU, that all shaders are rendering states are setup properly (e.g. texture is bound). Compare your code to existing backends and use a graphics debugger such as [RenderDoc](https://renderdoc.org) to debug your rendering states.
 
 ##### [Return to Index](#index)
@@ -375,23 +376,49 @@ node open/closed state differently. See what makes more sense in your situation!
 
 ---
 
-### Q: How can I display an image? What is ImTextureID, how does it work?
+### Q: How can I display an image?
+### Q: What are ImTextureID/ImTextureRef?
 
-Short explanation:
+**Short explanation:**
 - Refer to [Image Loading and Displaying Examples](https://github.com/ocornut/imgui/wiki/Image-Loading-and-Displaying-Examples) on the [Wiki](https://github.com/ocornut/imgui/wiki).
 - You may use functions such as `ImGui::Image()`, `ImGui::ImageButton()` or lower-level `ImDrawList::AddImage()` to emit draw calls that will use your own textures.
 - Actual textures are identified in a way that is up to the user/engine. Those identifiers are stored and passed as an opaque ImTextureID value.
 - By default ImTextureID can store up to 64-bits. You may `#define` it to a custom type/structure if you need.
 - Loading image files from the disk and turning them into a texture is not within the scope of Dear ImGui (for a good reason), but the examples linked above may be useful references.
 
+**Details:**
+
+1.92 introduced `ImTextureRef` in June 2025.
+- Most drawing functions using ImTextureID were changed to use ImTextureRef.
+- We intentionally do not provide an implicit ImTextureRef -> ImTextureID cast operator because it is technically lossy to convert ImTextureRef to ImTextureID before rendering.
+
+**ImTextureID = backend specific, low-level identifier for a texture uploaded in GPU/graphics system.**
+- When a Rendered Backend creates a texture, it store its native identifier into a ImTextureID value (e.g. Used by DX11 backend to a `ID3D11ShaderResourceView*`; Used by OpenGL backends to store `GLuint`; Used by SDLGPU backend to store a `SDL_GPUTextureSamplerBinding*`, etc.).
+- User may submit their own textures to e.g. ImGui::Image() function by passing the same type.
+- During the rendering loop, the Renderer Backend retrieve the ImTextureID, which stored inside a ImTextureRef, which is stored inside ImDrawCmd.
+- Compile-time type configuration:
+  - To use something other than a 64-bit value: add '#define ImTextureID MyTextureType*' in your imconfig.h file.
+  - This can be whatever to you want it to be! read the FAQ entry about textures for details.
+  - You may decide to store a higher-level structure containing texture, sampler, shader etc. with various constructors if you like. You will need to implement ==/!= operators.
+
+**ImTextureRef = higher-level identifier for a texture.**
+- The identifier is valid even before the texture has been uploaded to the GPU/graphics system.
+- This is what gets passed to functions such as `ImGui::Image()`, `ImDrawList::AddImage()`.
+- This is what gets stored in draw commands (`ImDrawCmd`) to identify a texture during rendering.
+ - When a texture is created by user code (e.g. custom images), we directly stores the low-level `ImTextureID`.
+ - When a texture is created by the backend, we stores a `ImTextureData*` which becomes an indirection to extract the `ImTextureID` value during rendering, after texture upload has happened.
+ - There is no constructor to create a `ImTextureID` from a `ImTextureData*` as we don't expect this to be useful to the end-user, and it would be erroneously called by many legacy code.
+ - If you want to bind the current atlas when using custom rectangle, you can use `io.Fonts->TexRef`.
+ - Binding generators for languages such as C (which don't have constructors), should provide a helper, e.g. `inline ImTextureRef ImTextureRefFromID(ImTextureID tex_id) { ImTextureRef tex_ref = { ._TexData = NULL, .TexID = tex_id }; return tex_ref; }`
+
 **Please read documentations or tutorials on your graphics API to understand how to display textures on the screen before moving onward.**
 
 Long explanation:
 - Dear ImGui's job is to create "meshes", defined in a renderer-agnostic format made of draw commands and vertices. At the end of the frame, those meshes (ImDrawList) will be displayed by your rendering function. They are made up of textured polygons and the code to render them is generally fairly short (a few dozen lines). In the examples/ folder, we provide functions for popular graphics APIs (OpenGL, DirectX, etc.).
 - Each rendering function decides on a data type to represent "textures". The concept of what is a "texture" is entirely tied to your underlying engine/graphics API.
- We carry the information to identify a "texture" in the ImTextureID type.
+We carry the information to identify a "texture" in the ImTextureID type, which itself tends to be stored inside a ImTextureRef.
 ImTextureID default to ImU64 aka 8 bytes worth of data: just enough to store one pointer or integer of your choice.
-Dear ImGui doesn't know or understand what you are storing in ImTextureID, it merely passes ImTextureID values until they reach your rendering function.
+Dear ImGui doesn't know or understand what you are storing in ImTextureID, it merely passes values until they reach your rendering function.
 - In the [examples/](https://github.com/ocornut/imgui/tree/master/examples) backends, for each graphics API we decided on a type that is likely to be a good representation for specifying an image from the end-user perspective. This is what the _examples_ rendering functions are using:
 ```cpp
 OpenGL:
@@ -539,30 +566,49 @@ ImGui::End();
 
 ### Q: How should I handle DPI in my application?
 
-The short answer is: obtain the desired DPI scale, load your fonts resized with that scale (always round down fonts size to the nearest integer), and scale your Style structure accordingly using `style.ScaleAllSizes()`.
+Since 1.92 (June 2025) fonts may be dynamically used at any size.
 
-Your application may want to detect DPI change and reload the fonts and reset style between frames.
+**Scaling fonts**
 
-Your UI code should avoid using hardcoded constants for size and positioning. Prefer to express values as multiple of reference values such as `ImGui::GetFontSize()` or `ImGui::GetFrameHeight()`. So e.g. instead of seeing a hardcoded height of 500 for a given item/window, you may want to use `30*ImGui::GetFontSize()` instead.
+To change font size:
+```cpp
+ImGui::PushFontSize(42.0f);
+```
+To change font and font size:
+```cpp
+ImGui::PushFont(new_font, 42.0f);
+```
+To scale all fonts:
+```cpp
+style.FontScaleDpi = 2.0f;
+```
+In `docking` branch or with multi-viewports:
+```cpp
+io.ConfigDpiScaleFonts = true;          // [Experimental] Automatically overwrite style.FontScaleDpi in Begin() when Monitor DPI changes. This will scale fonts but _NOT_ scale sizes/padding for now.
+io.ConfigDpiScaleViewports = true;      // [Experimental] Scale Dear ImGui and Platform Windows when Monitor DPI changes.
+```
 
-Down the line Dear ImGui will provide a variety of standardized reference values to facilitate using this.
+**Scaling style** (paddings, spacings, thicknesses)
 
-Applications in the `examples/` folder are not DPI aware partly because they are unable to load a custom font from the file-system (may change that in the future).
+This is still massively work in progress, expect turbulence.
+Style values are currently not easily scalable dynamically.
+For single viewport application you can call once:
+```cpp
+style.ScaleAllSizes(factor); // call once!
+```
+If you need to change the scaling factor, it is currently most practical to reset the style and call this again with a new value.
 
-The reason DPI is not auto-magically solved in stock examples is that we don't yet have a satisfying solution for the "multi-dpi" problem (using the `docking` branch: when multiple viewport windows are over multiple monitors using different DPI scales). The current way to handle this on the application side is:
-- Create and maintain one font atlas per active DPI scale (e.g. by iterating `platform_io.Monitors[]` before `NewFrame()`).
-- Hook `platform_io.OnChangedViewport()` to detect when a `Begin()` call makes a Dear ImGui window change monitor (and therefore DPI).
-- In the hook: swap atlas, swap style with correctly sized one, and remap the current font from one atlas to the other (you may need to maintain a remapping table of your fonts at varying DPI scales).
+Your UI code should avoid using hardcoded constants for size and positioning. Prefer to express values as multiple of reference values such as `ImGui::GetFontSize()` or `ImGui::GetFrameHeight()`. So e.g. instead of seeing a hardcoded height of 500 for a given item/window, you may want to use `30*ImGui::GetFontSize()` instead.
 
-This approach is relatively easy and functional but comes with two issues:
-- It's not possibly to reliably size or position a window ahead of `Begin()` without knowing on which monitor it'll land.
-- Style override may be lost during the `Begin()` call crossing monitor boundaries. You may need to do some custom scaling mumbo-jumbo if you want your `OnChangedViewport()` handler to preserve style overrides.
+Down the line Dear ImGui will provide a variety of standardized reference values to facilitate using this. This is expected to happen during subsequent 1.92.x releases.
 
-Please note that if you are not using multi-viewports with multi-monitors using different DPI scales, you can ignore that and use the simpler technique recommended at the top.
+Applications in the `examples/` folder are partly DPI aware but they are unable to load a custom font from the file-system, so they look ugly (may change that in the future).
 
-On Windows, in addition to scaling the font size (make sure to round to an integer) and using `style.ScaleAllSizes()`, you will need to inform Windows that your application is DPI aware. If this is not done, Windows will scale the application window and the UI text will be blurry. Potential solutions to indicate DPI awareness on Windows are:
+The reason DPI is not auto-magically solved in stock examples is that we don't yet have a satisfying solution for the "multi-dpi" problem (using the `docking` branch: when multiple viewport windows are over multiple monitors using different DPI scales) specifically for the `ImGuiStyle` structure. Fonts are however now perfectly scalable.
 
-- For SDL2: the flag `SDL_WINDOW_ALLOW_HIGHDPI` needs to be passed to `SDL_CreateWindow()`.
+**On Windows, you need to inform Windows that your application is DPI aware!**
+If this is not done, Windows will scale the application window and the UI text will be blurry. Potential solutions to indicate DPI awareness on Windows are:
+- For SDL2: the flag `SDL_WINDOW_ALLOW_HIGHDPI` needs to be passed to `SDL_CreateWindow()` + call `::SetProcessDPIAware()`.
 - For SDL3: the flag `SDL_WINDOW_HIGH_PIXEL_DENSITY` needs to be passed to `SDL_CreateWindow()`.
 - For GLFW: this is done automatically.
 - For other Windows projects with other backends, or wrapper projects:
@@ -615,9 +661,12 @@ Use the font atlas to pack them into a single texture. Read [docs/FONTS.md](http
 ---
 
 ### Q: How can I display and input non-Latin characters such as Chinese, Japanese, Korean, Cyrillic?
-When loading a font, pass custom Unicode ranges to specify the glyphs to load.
 
+Since 1.92 (June 2025) and with an updated backend, it is not necessary to specify glyph ranges at all.
+
+Before 1.92, when loading a font, pass custom Unicode ranges to specify the glyphs to load.
 ```cpp
+// [BEFORE 1.92]
 // Add default Japanese ranges
 io.Fonts->AddFontFromFileTTF("myfontfile.ttf", size_in_pixels, nullptr, io.Fonts->GetGlyphRangesJapanese());
 
@@ -641,8 +690,8 @@ Text input: it is up to your application to pass the right character code by cal
 The applications in examples/ are doing that.
 Windows: you can use the WM_CHAR or WM_UNICHAR or WM_IME_CHAR message (depending if your app is built using Unicode or MultiByte mode).
 You may also use `MultiByteToWideChar()` or `ToUnicode()` to retrieve Unicode codepoints from MultiByte characters or keyboard state.
-Windows: if your language is relying on an Input Method Editor (IME), you can write your HWND to ImGui::GetMainViewport()->PlatformHandleRaw
-for the default implementation of GetPlatformIO().Platform_SetImeDataFn() to set your Microsoft IME position correctly.
+Windows: if your language is relying on an Input Method Editor (IME), you can write your HWND to `ImGui::GetMainViewport()->PlatformHandleRaw`
+for the default implementation of `GetPlatformIO().Platform_SetImeDataFn()` to set your Microsoft IME position correctly.
 
 ##### [Return to Index](#index)
 

docs/FONTS.md

@@ -12,7 +12,7 @@ In the [misc/fonts/](https://github.com/ocornut/imgui/tree/master/misc/fonts) fo
 
 ## Index
 - [Troubleshooting](#troubleshooting)
-- [New! Dynamic Fonts system in 1.92 (March 2025)](#new-dynamic-fonts-system-in-192-march-2025)
+- [New! Dynamic Fonts system in 1.92 (June 2025)](#new-dynamic-fonts-system-in-192-june-2025)
 - [How should I handle DPI in my application?](#how-should-i-handle-dpi-in-my-application)
 - [Fonts Loading Instructions](#fonts-loading-instructions)
 - [Loading Font Data from Memory](#loading-font-data-from-memory)
@@ -72,11 +72,11 @@ Future versions of Dear ImGui should solve this problem.
 
 ---------------------------------------
 
-## New! Dynamic Fonts system in 1.92 (March 2025+)
+## New! Dynamic Fonts system in 1.92 (June 2025)
 
-v1.92 will introduce a newer, dynamic font system. It requires backend to support the `ImGuiBackendFlags_HasTextures` feature:
+v1.92 introduces a newer, dynamic font system. It requires backend to support the `ImGuiBackendFlags_HasTextures` feature:
 - Users of icons, Asian and non-English languages do not need to pre-build all glyphs ahead of time. Saving on loading time, memory, and also reducing issues with missing glyphs. Specifying glyph ranges is not needed anymore.
-- PushFontSize() may be used anytime to change font size.
+- `PushFontSize()` may be used anytime to change font size.
 - Packing custom rectangles is more convenient as pixels may be written to immediately.
 - Any update to fonts previously required backend specific calls to re-upload the texture, and said calls were not portable across backends. It is now possible to scale fonts etc. in a way that doesn't require you to make backend-specific calls.
 - It is possible to plug a custom loader/backend to any font source.
@@ -105,6 +105,12 @@ io.Fonts->AddFontDefault();
 ```
 
 **Load .TTF/.OTF file with:**
+🆕 **Since 1.92, with an up to date backend: passing a size is not necessary**
+```cpp
+ImGuiIO& io = ImGui::GetIO();
+io.Fonts->AddFontFromFileTTF("font.ttf");
+```
+**Before 1.92, or without an up to date backend:**
 ```cpp
 ImGuiIO& io = ImGui::GetIO();
 io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels);
@@ -115,8 +121,8 @@ If you get an assert stating "Could not load font file!", your font filename is
 ```cpp
 // Init
 ImGuiIO& io = ImGui::GetIO();
-ImFont* font1 = io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels);
-ImFont* font2 = io.Fonts->AddFontFromFileTTF("anotherfont.otf", size_pixels);
+ImFont* font1 = io.Fonts->AddFontFromFileTTF("font.ttf",);
+ImFont* font2 = io.Fonts->AddFontFromFileTTF("anotherfont.otf");
 ```
 
 In your application loop, select which font to use:
@@ -135,6 +141,18 @@ ImFont* font = io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, &config);
 ```
 
 **Combine multiple fonts into one:**
+
+🆕 **Since 1.92, with an up to date backend: specifying glyph ranges is unnecessary.**
+```cpp
+// Load a first font
+ImFont* font = io.Fonts->AddFontDefault();
+ImFontConfig config;
+config.MergeMode = true;
+io.Fonts->AddFontFromFileTTF("DroidSans.ttf", 0.0f, &config);           // Merge into first font to add e.g. Asian characters
+io.Fonts->AddFontFromFileTTF("fontawesome-webfont.ttf", 0.0f, &config); // Merge into first font to add Icons
+io.Fonts->Build();
+```
+**Before 1.92, or without an up to date backend:**
 ```cpp
 // Load a first font
 ImFont* font = io.Fonts->AddFontDefault();
@@ -152,8 +170,7 @@ io.Fonts->Build();
 
 **Add a fourth parameter to bake specific font ranges only:**
 
-🆕 **Since 1.92, with an up to date backend: specifying glyph ranges is necessary. All the GetGlyphRangesXXX() functions are marked obsolete.**
-
+🆕 **Since 1.92, with an up to date backend: specifying glyph ranges is unnecessary. All the GetGlyphRangesXXX() functions are marked obsolete.**
 ```cpp
 // Basic Latin, Extended Latin
 io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, nullptr, io.Fonts->GetGlyphRangesDefault());
@@ -169,14 +186,12 @@ See [Using Custom Glyph Ranges](#using-custom-glyph-ranges) section to create yo
 **Example loading and using a Japanese font:**
 
 🆕 **Since 1.92, with an up to date backend:**
-
 ```cpp
 ImGuiIO& io = ImGui::GetIO();
-io.Fonts->AddFontFromFileTTF("NotoSansCJKjp-Medium.otf", 20.0f);
+io.Fonts->AddFontFromFileTTF("NotoSansCJKjp-Medium.otf");
 ```
 
 **Before 1.92, or without an up to date backend:**
-
 ```cpp
 ImGuiIO& io = ImGui::GetIO();
 io.Fonts->AddFontFromFileTTF("NotoSansCJKjp-Medium.otf", 20.0f, nullptr, io.Fonts->GetGlyphRangesJapanese());
@@ -248,14 +263,24 @@ To refer to the icon UTF-8 codepoints from your C++ code, you may use those head
 
 So you can use `ICON_FA_SEARCH` as a string that will render as a "Search" icon.
 
-🆕 **Since 1.92, with an up to date backend: specifying glyph ranges is necessary. You can omit this parameter.**
-
+🆕 **Since 1.92, with an up to date backend: specifying glyph ranges is unnecessary. You can omit this parameter.**
 Example Setup:
 ```cpp
 // Merge icons into default tool font
 #include "IconsFontAwesome.h"
 ImGuiIO& io = ImGui::GetIO();
 io.Fonts->AddFontDefault();
+ImFontConfig config;
+config.MergeMode = true;
+config.GlyphMinAdvanceX = 13.0f; // Use if you want to make the icon monospaced
+io.Fonts->AddFontFromFileTTF("fonts/fontawesome-webfont.ttf", 13.0f, &config);
+```
+**Before 1.92:**
+```cpp
+// Merge icons into default tool font
+#include "IconsFontAwesome.h"
+ImGuiIO& io = ImGui::GetIO();
+io.Fonts->AddFontDefault();
 
 ImFontConfig config;
 config.MergeMode = true;
@@ -275,7 +300,8 @@ See Links below for other icons fonts and related tools.
 
 **Monospace Icons?**
 
-To make your icon look more monospace and facilitate alignment, you may want to set the ImFontConfig::GlyphMinAdvanceX value when loading an icon font.
+To make your icon look more monospace and facilitate alignment, you may want to set the `ImFontConfig::GlyphMinAdvanceX` value when loading an icon font.
+If you `GlyphMinAdvanceX` you need to pass a `font_size` to `AddFontXXX()` calls, as the MinAdvanceX value will be specified for the given size and scaled otherwise.
 
 **Screenshot**
 
@@ -288,8 +314,8 @@ Here's an application using icons ("Avoyd", https://www.avoyd.com):
 
 ## Using FreeType Rasterizer (imgui_freetype)
 
-- Dear ImGui uses imstb\_truetype.h to rasterize fonts (with optional oversampling). This technique and its implementation are not ideal for fonts rendered at small sizes, which may appear a little blurry or hard to read.
-- There is an implementation of the ImFontAtlas builder using FreeType that you can use in the [misc/freetype/](https://github.com/ocornut/imgui/tree/master/misc/freetype) folder.
+- Dear ImGui uses [stb_truetype.h](https://github.com/nothings/stb/) to rasterize fonts (with optional oversampling). This technique and its implementation are not ideal for fonts rendered at small sizes, which may appear a little blurry or hard to read.
+- You can however use `imgui_freetype.cpp` from the [misc/freetype/](https://github.com/ocornut/imgui/tree/master/misc/freetype) folder.
 - FreeType supports auto-hinting which tends to improve the readability of small fonts.
 - Read documentation in the [misc/freetype/](https://github.com/ocornut/imgui/tree/master/misc/freetype) folder.
 - Correct sRGB space blending will have an important effect on your font rendering quality.
@@ -312,10 +338,9 @@ Here's an application using icons ("Avoyd", https://www.avoyd.com):
 io.Fonts->AddFontFromFileTTF("../../../imgui_dev/data/fonts/NotoSans-Regular.ttf", 16.0f);
 static ImWchar ranges[] = { 0x1, 0x1FFFF, 0 };
 static ImFontConfig cfg;
-cfg.OversampleH = cfg.OversampleV = 1;
 cfg.MergeMode = true;
-cfg.FontBuilderFlags |= ImGuiFreeTypeBuilderFlags_LoadColor;
-io.Fonts->AddFontFromFileTTF("C:\\Windows\\Fonts\\seguiemj.ttf", 16.0f, &cfg, ranges);
+cfg.FontLoaderFlags |= ImGuiFreeTypeLoaderFlags_LoadColor;
+io.Fonts->AddFontFromFileTTF("C:\\Windows\\Fonts\\seguiemj.ttf", 16.0f, &cfg);
 ```
 
 ##### [Return to Index](#index)
@@ -348,7 +373,7 @@ io.Fonts->Build();                                     // Build the atlas while
 🆕 **Since 1.92, with an up to date backend: this system has been revamped.**
 
 TL;DR; With the new system, it is recommended that you create a custom `ImFontLoader` and register your fonts with it.
-`AddCustomRectFontGlyph()` has been obsolete because its API does not make much sense with resizable fonts.
+`AddCustomRectFontGlyph()` has been obsoleted because its API does not make much sense with resizable fonts.
 
 You can ask questions in [#8466](https://github.com/ocornut/imgui/issues/8466).
 

imgui.h

@@ -314,18 +314,17 @@ IM_MSVC_RUNTIME_CHECKS_RESTORE
 
 // ImTextureID = backend specific, low-level identifier for a texture uploaded in GPU/graphics system.
 // [Compile-time configurable type]
-// Overview:
 // - When a Rendered Backend creates a texture, it store its native identifier into a ImTextureID value.
-//   (e.g. Used by DX11 backend to a `ID3D11ShaderResourceView*`; Used by OpenGL backends to store `GLuint';
+//   (e.g. Used by DX11 backend to a `ID3D11ShaderResourceView*`; Used by OpenGL backends to store `GLuint`;
 //         Used by SDLGPU backend to store a `SDL_GPUTextureSamplerBinding*`, etc.).
 // - User may submit their own textures to e.g. ImGui::Image() function by passing the same type.
-// - During the rendering loop, the Renderer Backend retrieve the ImTextureID, which stored inside
-//   ImTextureRef, which is stored inside ImDrawCmd.
-// Configuring the type:
-// - To use something other than a 64-bit value: add '#define ImTextureID MyTextureType*' in your imconfig.h file.
-// - This can be whatever to you want it to be! read the FAQ entry about textures for details.
-// - You may decide to store a higher-level structure containing texture, sampler, shader etc. with various
-//   constructors if you like. You will need to implement ==/!= operators.
+// - During the rendering loop, the Renderer Backend retrieve the ImTextureID, which stored inside a
+//   ImTextureRef, which is stored inside a ImDrawCmd.
+// - Compile-time type configuration:
+//   - To use something other than a 64-bit value: add '#define ImTextureID MyTextureType*' in your imconfig.h file.
+//   - This can be whatever to you want it to be! read the FAQ entry about textures for details.
+//   - You may decide to store a higher-level structure containing texture, sampler, shader etc. with various
+//     constructors if you like. You will need to implement ==/!= operators.
 // History:
 // - In v1.91.4 (2024/10/08): the default type for ImTextureID was changed from 'void*' to 'ImU64'. This allowed backends requirig 64-bit worth of data to build on 32-bit architectures. Use intermediary intptr_t cast and read FAQ if you have casting warnings.
 // - In v1.92.0 (2025/XX/XX): added ImTextureRef which carry either a ImTextureID either a pointer to internal texture atlas. All user facing functions taking ImTextureID changed to ImTextureRef
@@ -340,15 +339,15 @@ typedef ImU64 ImTextureID;      // Default: store up to 64-bits (any pointer or
 
 // ImTextureRef = higher-level identifier for a texture.
 // The identifier is valid even before the texture has been uploaded to the GPU/graphics system.
-// This is what gets passed to functions such as ImGui::Image(), ImDrawList::AddImage().
-// This is what gets stored in draw commands (ImDrawCmd) to identify a texture during rendering.
+// This is what gets passed to functions such as `ImGui::Image()`, `ImDrawList::AddImage()`.
+// This is what gets stored in draw commands (`ImDrawCmd`) to identify a texture during rendering.
 // - When a texture is created by user code (e.g. custom images), we directly stores the low-level ImTextureID.
 // - When a texture is created by the backend, we stores a ImTextureData* which becomes an indirection
 //   to extract the ImTextureID value during rendering, after texture upload has happened.
 // - There is no constructor to create a ImTextureID from a ImTextureData* as we don't expect this
 //   to be useful to the end-user, and it would be erroneously called by many legacy code.
 // - If you want to bind the current atlas when using custom rectangle, you can use io.Fonts->TexRef.
-// - Binding generators for languages such as C (which don't have constructors), should provide a helper:
+// - Binding generators for languages such as C (which don't have constructors), should provide a helper, e.g.
 //      inline ImTextureRef ImTextureRefFromID(ImTextureID tex_id) { ImTextureRef tex_ref = { ._TexData = NULL, .TexID = tex_id }; return tex_ref; }
 // In 1.92 we changed most drawing functions using ImTextureID to use ImTextureRef.
 // We intentionally do not provide an implicit ImTextureRef -> ImTextureID cast operator because it is technically lossy to convert ImTextureRef to ImTextureID before rendering.