Merge commit '17c41323d9a870a4c75d5dfc5def37f32278ced7' into back-to-imgui
This commit is contained in:
irisz64
2
external/imgui/docs/BACKENDS.md
vendored
2
external/imgui/docs/BACKENDS.md
vendored
@@ -12,7 +12,7 @@ _(You may browse this at https://github.com/ocornut/imgui/blob/master/docs/BACKE
|
||||
Dear ImGui is highly portable and only requires a few things to run and render, typically:
|
||||
|
||||
- Required: providing mouse/keyboard inputs (fed into the `ImGuiIO` structure).
|
||||
- Required: uploading the font atlas texture into graphics memory.
|
||||
- Required: creating, updating and destroying textures.
|
||||
- Required: rendering indexed textured triangles with a clipping rectangle.
|
||||
|
||||
Extra features are opt-in, our backends try to support as many as possible:
|
||||
|
||||
452
external/imgui/docs/CHANGELOG.txt
vendored
452
external/imgui/docs/CHANGELOG.txt
vendored
@@ -36,34 +36,345 @@ HOW TO UPDATE?
|
||||
- Please report any issue!
|
||||
|
||||
-----------------------------------------------------------------------
|
||||
VERSION 1.92.0 WIP (In Progress)
|
||||
VERSION 1.92.0 (Released 2025-06-25)
|
||||
-----------------------------------------------------------------------
|
||||
|
||||
Decorated log and release notes: https://github.com/ocornut/imgui/releases/tag/v1.92
|
||||
|
||||
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 INTERFERENCE,
|
||||
BUT INEVITABLY SOME USERS OR THIRD-PARTY EXTENSIONS 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/
|
||||
If you are using custom widgets, internals or third-party extension that are somehow
|
||||
breaking and aren't obvious how to solve, please post in Issues so we can gather
|
||||
data and share solutions that may help others.
|
||||
|
||||
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:
|
||||
|
||||
- Backends: SDL3: Fixed casing typo in function name: (#8509, #8163, #7998, #7988) [@puugz]
|
||||
- Imgui_ImplSDLGPU3_PrepareDrawData() -> ImGui_ImplSDLGPU3_PrepareDrawData()
|
||||
- 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+),
|
||||
- This should be all automatic.
|
||||
- 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.
|
||||
- Fonts: **IMPORTANT** on Font Sizing:
|
||||
- Before 1.92, fonts were of a single size. They can now be dynamically sized.
|
||||
- PushFont() API now has a REQUIRED size parameter.
|
||||
void PushFont(ImFont* font) --> void PushFont(ImFont* font, float size);
|
||||
- PushFont(font, 0.0f) // Change font and keep current size
|
||||
- PushFont(NULL, 20.0f) // Keep font and change current size
|
||||
- PushFont(font, 20.0f) // Change font and set size to 20.0f
|
||||
- PushFont(font, style.FontSizeBase * 2.0f) // Change font and set size to be twice bigger than current size.
|
||||
- PushFont(font, font->LegacySize) // Change font and set size to size passed to AddFontXXX() function. Same as pre-1.92 behavior, for fixed size fonts.
|
||||
- To use old behavior use 'ImGui::PushFont(font, font->LegacySize)' at call site.
|
||||
We intentionally didn't add a default parameter because it would make the long-term
|
||||
transition more difficult.
|
||||
- Kept inline redirection font. Will obsolete.
|
||||
- Global scale factors may be applied over the provided size.
|
||||
This is why it is called 'FontSizeBase' in the style structure.
|
||||
- Global scale factors are: 'style.FontScaleMain', 'style.FontScaleDpi' and maybe more.
|
||||
- ImFont::FontSize was removed and does not make sense anymore.
|
||||
- ImFont::LegacySize is the size passed to AddFont().
|
||||
- Removed support for old PushFont(NULL) which was a shortcut for "revert to default font".
|
||||
`PushFont(NULL, some_size)` now keeps current change and changes size.
|
||||
- Renamed/moved 'io.FontGlobalScale' to 'style.FontScaleMain'.
|
||||
- Fonts: **IMPORTANT** on Font Merging:
|
||||
- When searching for a glyph in multiple merged fonts: font inputs are now scanned in order
|
||||
for the first font input which the desired glyph. This is technically a different behavior
|
||||
than before!
|
||||
- e.g. If you are merging fonts you may have glyphs that you expected to load from
|
||||
Font Source 2 which exists in Font Source 1. After the update and when using a new backend,
|
||||
those glyphs may now loaded from Font Source 1!
|
||||
- You can use `ImFontConfig::GlyphExcludeRanges[]` to specify ranges to ignore in given Input:
|
||||
// Add Font Source 1 but ignore ICON_MIN_FA..ICON_MAX_FA range
|
||||
static ImWchar exclude_ranges[] = { ICON_MIN_FA, ICON_MAX_FA, 0 };
|
||||
ImFontConfig cfg1;
|
||||
cfg1.GlyphExcludeRanges = exclude_ranges;
|
||||
io.Fonts->AddFontFromFileTTF("segoeui.ttf", 0.0f, &cfg1);
|
||||
// Add Font Source 2, which expects to use the range above
|
||||
ImFontConfig cfg2;
|
||||
cfg2.MergeMode = true;
|
||||
io.Fonts->AddFontFromFileTTF("FontAwesome4.ttf", 0.0f, &cfg2);
|
||||
- You can use `Metrics/Debugger->Fonts->Font->Input Glyphs Overlap Detection Tool` to
|
||||
see list of glyphs available in multiple font sources. This can facilitate understanding
|
||||
which font input is providing which glyph.
|
||||
|
||||
Other changes:
|
||||
- Textures:
|
||||
- All API functions taking a 'ImTextureID' parameter are now taking a 'ImTextureRef':
|
||||
- ImTextureRef ais 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 call ImFontAtlasUpdateNewFrame() yourself.
|
||||
An assert will trigger if you don't.
|
||||
- Fonts: obsoleted ImGui::SetWindowFontScale() which is not useful anymore. Prefer using
|
||||
PushFont(NULL, 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, ....);
|
||||
The leading 'float scale' parameters was changed to 'float size'.
|
||||
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.
|
||||
- Fields 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().
|
||||
- Layout: commented out legacy ErrorCheckUsingSetCursorPosToExtendParentBoundaries() fallback
|
||||
obsoleted in 1.89 (August 2022) which allowed a SetCursorPos()/SetCursorScreenPos() call WITHOUT AN ITEM
|
||||
to extend parent window/cell boundaries. Replaced with assert/tooltip that would already happens if
|
||||
previously using IMGUI_DISABLE_OBSOLETE_FUNCTIONS. (#5548, #4510, #3355, #1760, #1490, #4152, #150)
|
||||
- Incorrect way to make a window content size 200x200:
|
||||
Begin(...) + SetCursorScreenPos(GetCursorScreenPos() + ImVec2(200,200)) + End();
|
||||
- Correct ways to make a window content size 200x200:
|
||||
Begin(...) + SetCursorScreenPos(GetCursorScreenPos() + ImVec2(200,200)) + Dummy(ImVec2(0,0)) + End();
|
||||
Begin(...) + Dummy(ImVec2(200,200)) + End();
|
||||
- TL;DR; if the assert triggers, you can add a Dummy({0,0}) call to validate extending parent boundaries.
|
||||
- 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);
|
||||
- PopAllowKeyboardFocus() --> PopItemFlag().
|
||||
- Commented out ImGuiListClipper::ForceDisplayRangeByIndices() which was obsoleted
|
||||
in 1.89.6 (June 2023).
|
||||
- ForceDisplayRangeByIndices() --> IncludeItemsByIndex()
|
||||
- Backends: SDL3: Fixed casing typo in function name: (#8509, #8163, #7998, #7988) [@puugz]
|
||||
- Imgui_ImplSDLGPU3_PrepareDrawData() --> ImGui_ImplSDLGPU3_PrepareDrawData()
|
||||
- Internals: RenderTextEllipsis() function removed the 'float clip_max_x' parameter directly
|
||||
preceding 'float ellipsis_max_x'. Values were identical for a vast majority of users. (#8387)
|
||||
- [Docking] renamed/moved ImGuiConfigFlags_DpiEnableScaleFonts -> bool io.ConfigDpiScaleFonts.
|
||||
- [Docking] renamed/moved ImGuiConfigFlags_DpiEnableScaleViewports -> bool io.ConfigDpiScaleViewports.
|
||||
**Neither of those flags are very useful in current code. They will be useful once we merge font changes.**
|
||||
|
||||
Non-breaking Fonts/Textures related 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 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_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.
|
||||
- Fonts: reworked text ellipsis logic to ensure a "..." is always displayed instead
|
||||
of a single character. (#7024)
|
||||
- Fonts: word-wrapping code handle ideographic comma & full stop (U+3001, U+3002). (#8540)
|
||||
- Fonts: fixed CalcWordWrapPosition() fallback when width is too small to wrap:
|
||||
would use a +1 offset instead of advancing to the next UTF-8 codepoint. (#8540)
|
||||
- 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.
|
||||
- Renderer Backends:
|
||||
- Backends: DX9/DX10/DX11/DX12, Vulkan, OpenGL2/3, Metal, SDLGPU3, SDLRenderer2/3, WebGPU, Allegro5:
|
||||
- Added ImGuiBackendFlags_RendererHasTextures support for all backends. (#8465, #3761, #3471)
|
||||
[@ocornut, @ShironekoBen, @thedmd]
|
||||
- Added ImGui_ImplXXXX_UpdateTexture(ImTextureData* tex) functions for all backends.
|
||||
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)
|
||||
- Special thanks for fonts/texture related feedback to: @thedmd, @ShironekoBen, @rodrigorc,
|
||||
@pathogendavid, @itamago, @rokups, @DucaRii, @Aarkham, @cyfewlp.
|
||||
|
||||
Other Changes:
|
||||
|
||||
- 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
|
||||
- Windows: fixed SetNextWindowCollapsed()/SetWindowCollapsed() bypassing the
|
||||
codepath that preserve last contents size when collapsed, resulting in
|
||||
programmatically uncollapsing auto-sizing windows having them flicker size
|
||||
for a frame. (#7691) [@achabense]
|
||||
- Windows: clicking on a window close button doesn't claim focus and bring to front. (#8683)
|
||||
- Windows: loosened code to allow hovering of resize grips, borders, and table
|
||||
borders while hovering a sibling child window, so that the code in master matches
|
||||
one in docking (they accidentally diverged). (#8554)
|
||||
- Windows: BeginChild(): fixed being unable to combine manual resize on one axis
|
||||
and automatic resize on the other axis. (#8690)
|
||||
e.g. neither ImGuiChildFlags_ResizeX | ImGuiChildFlags_AutoResizeY
|
||||
or ImGuiChildFlags_ResizeY | ImGuiChildFlags_AutoResizeX worked before.
|
||||
- TreeNode: added experimental flags to draw tree hierarchy outlines linking
|
||||
parent and tree nodes: (#2920)
|
||||
- ImGuiTreeNodeFlags_DrawLinesNone: No lines drawn (default value in style.TreeLinesFlags).
|
||||
- ImGuiTreeNodeFlags_DrawLinesFull: Horizontal lines to child nodes. Vertical line drawn down to TreePop() position: cover full contents.
|
||||
- ImGuiTreeNodeFlags_DrawLinesToNodes: Horizontal lines to child nodes. Vertical line drawn down to bottom-most child node.
|
||||
- Added style.TreeLinesFlags which stores the default setting,
|
||||
which may be overriden in individual TreeNode() calls.
|
||||
- Added style.TreeLinesFlags which stores the default setting,
|
||||
which may be overridden in individual TreeNode() calls.
|
||||
- Added style.TreeLinesSize (default to 1.0f).
|
||||
- Added ImGuiCol_TreeLines (in default style this is the same as ImGuiCol_Border).
|
||||
- Added style.TreeLinesRadius (default to 0.0f).
|
||||
- Added ImGuiCol_TreeLines (in default styles this is the same as ImGuiCol_Border).
|
||||
- Caveats:
|
||||
- Tree nodes may be used in many creative ways (manually positioning openable
|
||||
nodes in unusual ways, using indent to create tree-looking structures, etc.)
|
||||
@@ -75,40 +386,132 @@ Other changes:
|
||||
- The feature is unlikely to ever work properly when using a coarse clipper
|
||||
such as ImGuiListClipper.
|
||||
- TreeNode: fixed incorrect clipping of arrow/bullet when using ImGuiTreeNodeFlags_SpanAllColumns.
|
||||
- InputText: fixed cursor positioning issue using up/down keys near end of lines while
|
||||
editing non-ASCII text. (Regression from 1.91.2) (#8635, #7925)
|
||||
- InputText: fixed a buffer overrun that could happen when using dynamically resizing
|
||||
buffers (e.g. imgui_stdlib.cpp for std::string, or ImGuiInputTextFlags_CallbackRezize)
|
||||
and programmatically making an insertion. (#8689) [@ocornut, @m9710797]
|
||||
- Tables: fixed TableHeader() eager vertical clipping of text which may be noticeable
|
||||
with FramePadding.y was too small. (#6236)
|
||||
- Tables: fixed an assert when combining Tables, Frozen Rows, Clipper and BeginMultiSelect()
|
||||
in a certain order. (#8595, #8250)
|
||||
- Tabs: fixes small issues with how "..." ellipsis moved depending on visibility
|
||||
of Close Button or Unsaved Document marker. (#8387)
|
||||
- Tooltips: tooltips have a maximum size corresponding to host display/monitor size,
|
||||
which mitigates edge case issues in multi-viewport scenarios where abnormally large
|
||||
windows (e.g. determined programmatically) can lead to renderer backend trying to
|
||||
create abnormally large framebuffers.
|
||||
- TextLinkOpenURL(): added bool return value on click. (#8645, #8451, #7660)
|
||||
- Scroll: fixed contents size, scrollbar visibility and scrolling resetting issues
|
||||
with abnormally large contents ranges. (#3609, #8215)
|
||||
- Clipper: some mitigation/improvements for abnormally large contents ranges. (#3609, #8215)
|
||||
- Nav: fixed assertion when holding gamepad FaceLeft/West button to open
|
||||
CTRL+Tab windowing + pressing a keyboard key. (#8525)
|
||||
- Nav: fixed scroll fallback (when there are no interactive widgets to jump to) not
|
||||
being enabled on windows with menu or title bar.
|
||||
- Nav: fixed an issue handling PageUp/PageDown on windows with abnormally large contents
|
||||
range which could lead to clipper requesting very large ranges.
|
||||
- Error Handling: added better error report and recovery for extraneous
|
||||
EndPopup() call. (#1651, #8499)
|
||||
- Fonts: word-wrapping code handle ideographic comma & full stop (U+3001, U+3002). (#8540)
|
||||
- Fonts: fixed CalcWordWrapPositionA() fallback when width is too small to wrap:
|
||||
would use a +1 offset instead of advancing to the next UTF-8 codepoint. (#8540)
|
||||
- Error Handling: added better error report and recovery when calling EndFrame()
|
||||
or Render() without NewFrame(). Was previously only an assert.
|
||||
- Style, InputText: added ImGuiCol_InputTextCursor to configure color of
|
||||
the InputText cursor/caret. (#7031)
|
||||
- Platform IME: added ImGuiPlatformImeData::ViewportId info (backported from Docking branch).
|
||||
- Platform IME: added ImGuiPlatformImeData::WantTextInput which might set independently
|
||||
of WantVisible. This is set in the same structure because activating text input generally
|
||||
requires providing a window to the backend. (#8584, #6341)
|
||||
- DrawList: Fixed a regression from 1.91.1 where a Begin()/PushFont()/AddImage() sequence
|
||||
would not restore the correct atlas Texture Identifier when the PushFont() call used
|
||||
a font from a different atlas. (#8694, caused by #3224, #3875, #6398, #7903)
|
||||
- Misc: added extra operators to ImVec4 in IMGUI_DEFINE_MATH_OPERATORS block. (#8510) [@gan74]
|
||||
- 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: SDL3: Update for SDL3 api changes: revert SDL_GetClipboardText()
|
||||
memory ownership change. (#8530, #7801) [@Green-Sky]
|
||||
- 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: 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)
|
||||
- Misc: removed static linkage from operators to facilitate using in C++ modules. (#8682, #8358) [@johmani]
|
||||
- Demo: changed default framed item width to use Min(GetFontSize() * 12, GetContentRegionAvail().x * 0.40f).
|
||||
- Renderer Backends:
|
||||
- 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: DirectX12: Fixed build on MinGW. (#8702, #4594) [@playday3008]
|
||||
- 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]
|
||||
- Platform Backends:
|
||||
- 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: GLFW: Added support for multiple Dear ImGui contexts. (#8676, #8239, #8069)
|
||||
- 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: SDL3: fixed pulling SDL_PROP_WINDOW_COCOA_WINDOW_POINTER into
|
||||
viewport->PlatformHandleRaw. (#8725, #8726) [@eertbleyen]
|
||||
- Backends: OSX: ImGui_ImplOSX_HandleEvent() only process event for window containing
|
||||
our view. (#8644) [@BingoXuan]
|
||||
- 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]
|
||||
|
||||
Docking+Viewports Branch:
|
||||
|
||||
- Backends: Win32: Viewports: fixed an issue when closing a window from
|
||||
- Viewports: added per-viewport FramebufferScale for Retina display multi-monitor support.
|
||||
Backend must provide platform_io.platform_io.Platform_GetWindowFramebufferScale handler.
|
||||
This effectively fixes clipping/rendering on multi-monitors with varying Retina scale.
|
||||
(#1065, #1542, #1676, #1786, #2826, #3757, #5081, #5580, #5592, #6465, #7273, #7779 etc.)
|
||||
- Viewports: fixed handling of simultaneous move + resize (e.g. toggling maximized)
|
||||
when ImGuiConfigFlags_DpiEnableScaleViewports is enabled.
|
||||
- Backends: Win32: Viewports: fixed an issue when closing a window from
|
||||
the OS close button (with io.ConfigViewportsNoDecoration=false) while
|
||||
user code is discarding the 'bool *p_open=false output' from Begin().
|
||||
Because we allowed the Win32 window to close early, Windows destroyed
|
||||
it and our imgui window became not visible even though user code was
|
||||
still submitting it.
|
||||
- Backends: Win32: Viewports: handle WM_DPICHANGED in backend when
|
||||
ImGuiConfigFlags_DpiEnableScaleViewports is enabled.
|
||||
- Backends: GLFW, SDL2, SDL3, Apple: provide Platform_GetWindowFramebufferScale handler,
|
||||
(#1065, #1542, #1676, #1786, #2826, #3757, #5081, #5580, #5592, #6465, #7273, #7779 etc.)
|
||||
- Backends: SDLGPU3 for SDL3: added multi-viewport support. (#8573) [@Lekoopapaul]
|
||||
- Backends: SDL2, SDL3: revert updating monitors and work areas info every
|
||||
frame. Only do it on Windows to detect task-bar resize until we get an
|
||||
adequate event for it. (#8415, #8558)
|
||||
- Backends: SDL3: macOS: Fixed secondary-viewports not appearing on a different
|
||||
monitor than the main viewport. Because SDL_SetWindowParent() seems to restrict it.
|
||||
- Backends: GLFW: Disable multi-viewports under Wayland (require GLFW 3.4). (#8587)
|
||||
- Backends: GLFW: Fixed an issue where Win32 specific WndProc hook was not installed
|
||||
for all GLFW version, preventing mouse vs touch detection from working on
|
||||
secondary viewports.
|
||||
|
||||
|
||||
-----------------------------------------------------------------------
|
||||
@@ -215,6 +618,7 @@ Other changes:
|
||||
- Debug Tools: Added io.ConfigDebugHighlightIdConflictsShowItemPicker (defaults to true)
|
||||
to allow disabled Item Picker suggestion in user facing builds. (#7961, #7669)
|
||||
- Debug Tools: Tweaked layout of ID Stack Tool and always display full path. (#4631)
|
||||
- imgui_freetype: update lunasvg API to support v3.0+. (#8656, #6842, #6591) [@moretromain]
|
||||
- Misc: Various zealous warning fixes for newer version of Clang.
|
||||
- Misc: Added ImGuiMouseCursor_Wait and ImGuiMouseCursor_Progress mouse cursors
|
||||
(busy/wait/hourglass shape, with or without an arrow cursor).
|
||||
|
||||
101
external/imgui/docs/FAQ.md
vendored
101
external/imgui/docs/FAQ.md
vendored
@@ -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**
|
||||
|
||||
To change font size:
|
||||
```cpp
|
||||
ImGui::PushFont(NULL, 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.
|
||||
```
|
||||
|
||||
**Scaling style** (paddings, spacings, thicknesses)
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Down the line Dear ImGui will provide a variety of standardized reference values to facilitate using this.
|
||||
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.
|
||||
|
||||
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).
|
||||
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).
|
||||
|
||||
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).
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
- 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)
|
||||
|
||||
|
||||
153
external/imgui/docs/FONTS.md
vendored
153
external/imgui/docs/FONTS.md
vendored
@@ -2,7 +2,7 @@ _(You may browse this at https://github.com/ocornut/imgui/blob/master/docs/FONTS
|
||||
|
||||
## Dear ImGui: Using Fonts
|
||||
|
||||
The code in imgui.cpp embeds a copy of 'ProggyClean.ttf' (by Tristan Grimmer),
|
||||
The code in imgui.cpp embeds a copy of [ProggyClean.ttf](http://proggyfonts.net) (by Tristan Grimmer),
|
||||
a 13 pixels high, pixel-perfect font used by default. We embed it in the source code so you can use Dear ImGui without any file system access. ProggyClean does not scale smoothly, therefore it is recommended that you load your own file when using Dear ImGui in an application aiming to look nice and wanting to support multiple resolutions.
|
||||
|
||||
You may also load external .TTF/.OTF files.
|
||||
@@ -12,11 +12,13 @@ In the [misc/fonts/](https://github.com/ocornut/imgui/tree/master/misc/fonts) fo
|
||||
|
||||
## Index
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [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)
|
||||
- [Loading Font Data Embedded In Source Code](#loading-font-data-embedded-in-source-code)
|
||||
- [Using Icon Fonts](#using-icon-fonts)
|
||||
- [Excluding Overlapping Ranges](#excluding-overlapping-ranges)
|
||||
- [Using FreeType Rasterizer (imgui_freetype)](#using-freetype-rasterizer-imgui_freetype)
|
||||
- [Using Colorful Glyphs/Emojis](#using-colorful-glyphsemojis)
|
||||
- [Using Custom Glyph Ranges](#using-custom-glyph-ranges)
|
||||
@@ -35,7 +37,7 @@ In the [misc/fonts/](https://github.com/ocornut/imgui/tree/master/misc/fonts) fo
|
||||
|
||||
### (1) Invalid filename due to use of `\` or unexpected working directory.
|
||||
|
||||
See [About Filenames](#about-filenames). AddFontXXX functions should assert if the filename is incorrect.
|
||||
See [About Filenames](#about-filenames). AddFontXXX() functions should assert if the filename is incorrect.
|
||||
|
||||
### (2) Invalid UTF-8 encoding of your non-ASCII strings.
|
||||
|
||||
@@ -43,14 +45,18 @@ See [About UTF-8 Encoding](#about-utf-8-encoding). Use the encoding viewer to co
|
||||
|
||||
### (3) Missing glyph ranges.
|
||||
|
||||
You need to load a font with explicit glyph ranges if you want to use non-ASCII characters. See [Fonts Loading Instructions](#fonts-loading-instructions). Use [Debug Tools](#debug-tools) confirm loaded fonts and loaded glyph ranges.
|
||||
🆕 **Since 1.92, with an up to date backend: specifying glyph ranges is unnecessary.**
|
||||
|
||||
This is a current constraint of Dear ImGui (which we will lift in the future): when loading a font you need to specify which characters glyphs to load.
|
||||
⏪ Before 1.92: you need to load a font with explicit glyph ranges if you want to use non-ASCII characters. See [Fonts Loading Instructions](#fonts-loading-instructions). Use [Debug Tools](#debug-tools) confirm loaded fonts and loaded glyph ranges.
|
||||
|
||||
This was a previous constraint of Dear ImGui (lifted in 1.92): when loading a font you need to specify which characters glyphs to load.
|
||||
All loaded fonts glyphs are rendered into a single texture atlas ahead of time. Calling either of `io.Fonts->GetTexDataAsAlpha8()`, `io.Fonts->GetTexDataAsRGBA32()` or `io.Fonts->Build()` will build the atlas. This is generally called by the Renderer backend, e.g. `ImGui_ImplDX11_NewFrame()` calls it. **If you use custom glyphs ranges, make sure the array is persistent** and available during the calls to `GetTexDataAsAlpha8()/GetTexDataAsRGBA32()/Build()`.
|
||||
|
||||
### (4) Font atlas texture fails to upload to GPU.
|
||||
|
||||
This is often of byproduct of point 3. If you have large number of glyphs or multiple fonts, the texture may become too big for your graphics API. **The typical result of failing to upload a texture is if every glyph or everything appears as empty white rectangles.** Mind the fact that some graphics drivers have texture size limitation. If you are building a PC application, mind the fact that your users may use hardware with lower limitations than yours.
|
||||
🆕 **Since 1.92, with an up to date backend: atlas is built incrementally and dynamically resized, this is less likely to happen**
|
||||
|
||||
:rewind: This is often of byproduct of point 3. If you have large number of glyphs or multiple fonts, the texture may become too big for your graphics API. **The typical result of failing to upload a texture is if every glyph or everything appears as empty white rectangles.** Mind the fact that some graphics drivers have texture size limitation. If you are building a PC application, mind the fact that your users may use hardware with lower limitations than yours.
|
||||
|
||||
|
||||
|
||||
@@ -60,9 +66,22 @@ Some solutions:
|
||||
- Reduce glyphs ranges by calculating them from source localization data.
|
||||
You can use the `ImFontGlyphRangesBuilder` for this purpose and rebuilding your atlas between frames when new characters are needed. This will be the biggest win!
|
||||
- Set `io.Fonts.Flags |= ImFontAtlasFlags_NoPowerOfTwoHeight;` to disable rounding the texture height to the next power of two.
|
||||
- Set `io.Fonts.TexDesiredWidth` to specify a texture width to reduce maximum texture height (see comment in `ImFontAtlas::Build()` function).
|
||||
|
||||
Future versions of Dear ImGui should solve this problem.
|
||||
##### [Return to Index](#index)
|
||||
|
||||
---------------------------------------
|
||||
|
||||
## New! Dynamic Fonts system in 1.92 (June 2025)
|
||||
|
||||
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.
|
||||
- `PushFont(NULL, new_size)` 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.
|
||||
|
||||
See [#8465](https://github.com/ocornut/imgui/issues/8465) for more details.
|
||||
|
||||
|
||||
##### [Return to Index](#index)
|
||||
|
||||
@@ -85,6 +104,13 @@ 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");
|
||||
```
|
||||
:rewind: **Before 1.92, or without an up to date backend:**
|
||||
```cpp
|
||||
ImGuiIO& io = ImGui::GetIO();
|
||||
io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels);
|
||||
@@ -95,14 +121,14 @@ 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:
|
||||
```cpp
|
||||
ImGui::Text("Hello"); // use the default font (which is the first loaded font)
|
||||
ImGui::PushFont(font2);
|
||||
ImGui::PushFont(font2, 0.0f); // change font, keep current size
|
||||
ImGui::Text("Hello with another font");
|
||||
ImGui::PopFont();
|
||||
```
|
||||
@@ -110,11 +136,23 @@ ImGui::PopFont();
|
||||
**For advanced options create a ImFontConfig structure and pass it to the AddFont() function (it will be copied internally):**
|
||||
```cpp
|
||||
ImFontConfig config;
|
||||
config.RasterizerDensity = 2.0f;
|
||||
config.OversampleH = 1.0f;
|
||||
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();
|
||||
```
|
||||
:rewind: **Before 1.92, or without an up to date backend:**
|
||||
```cpp
|
||||
// Load a first font
|
||||
ImFont* font = io.Fonts->AddFontDefault();
|
||||
@@ -132,6 +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 unnecessary. All the GetGlyphRangesXXX() functions are marked obsolete.**
|
||||
```cpp
|
||||
// Basic Latin, Extended Latin
|
||||
io.Fonts->AddFontFromFileTTF("font.ttf", size_pixels, nullptr, io.Fonts->GetGlyphRangesDefault());
|
||||
@@ -146,10 +185,18 @@ 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");
|
||||
```
|
||||
|
||||
:rewind: **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());
|
||||
```
|
||||
|
||||
```cpp
|
||||
ImGui::Text(u8"こんにちは！テスト %d", 123);
|
||||
if (ImGui::Button(u8"ロード"))
|
||||
@@ -216,12 +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 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);
|
||||
```
|
||||
:rewind: **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;
|
||||
@@ -241,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**
|
||||
|
||||
@@ -252,11 +312,49 @@ Here's an application using icons ("Avoyd", https://www.avoyd.com):
|
||||
|
||||
---------------------------------------
|
||||
|
||||
### Excluding Overlapping Ranges
|
||||
|
||||
🆕 **Since 1.92, with an up to date backend: glyphs ranges are ignored**: when loading a glyph, input fonts in the merge list are queried in order. The first font which has the glyph loads it.
|
||||
<BR>‼️ **If you are merging several fonts, you may have undesirable overlapping ranges.** You can use `ImFontConfig::GlyphExcludeRanges[] `to specify ranges to ignore in a given Input.
|
||||
|
||||
```cpp
|
||||
// Add Font Source 1 but ignore ICON_MIN_FA..ICON_MAX_FA range
|
||||
static ImWchar exclude_ranges[] = { ICON_MIN_FA, ICON_MAX_FA, 0 };
|
||||
ImFontConfig cfg1;
|
||||
cfg1.GlyphExcludeRanges = exclude_ranges;
|
||||
io.Fonts->AddFontFromFileTTF("segoeui.ttf", 0.0f, &cfg1);
|
||||
|
||||
// Add Font Source 2, which expects to use the range above
|
||||
ImFontConfig cfg2;
|
||||
cfg2.MergeMode = true;
|
||||
io.Fonts->AddFontFromFileTTF("FontAwesome4.ttf", 0.0f, &cfg2);
|
||||
```
|
||||
Another (silly) example:
|
||||
```cpp
|
||||
// Remove 'A'-'Z' from first font
|
||||
static ImWchar exclude_ranges[] = { 'A', 'Z', 0 };
|
||||
ImFontConfig cfg1;
|
||||
cfg1.GlyphExcludeRanges = exclude_ranges;
|
||||
io.Fonts->AddFontFromFileTTF("segoeui.ttf", 0.0f, &cfg1);
|
||||
|
||||
// Load another font to fill the gaps
|
||||
ImFontConfig cfg2;
|
||||
cfg2.MergeMode = true;
|
||||
io.Fonts->AddFontFromFileTTF("Roboto-Medium.ttf", 0.0f, &cfg2);
|
||||
```
|
||||
|
||||
|
||||
You can use `Metrics/Debugger->Fonts->Font->Input Glyphs Overlap Detection Tool` to see list of glyphs available in multiple font sources. This can facilitate understanding which font input is providing which glyph.
|
||||
|
||||
##### [Return to Index](#index)
|
||||
|
||||
---------------------------------------
|
||||
|
||||
## 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.
|
||||
- FreeType supports auto-hinting which tends to improve the readability of small fonts.
|
||||
- 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. Compile with this file and add `#define IMGUI_ENABLE_FREETYPE` to your imconfig.h file or build system to automatically activate it.
|
||||
- FreeType supports auto-hinting which tends to improve the readability of small fonts. It makes a big difference especially at smaller resolutions.
|
||||
- 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.
|
||||
|
||||
@@ -278,10 +376,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)
|
||||
@@ -290,7 +387,9 @@ io.Fonts->AddFontFromFileTTF("C:\\Windows\\Fonts\\seguiemj.ttf", 16.0f, &cfg, ra
|
||||
|
||||
## Using Custom Glyph Ranges
|
||||
|
||||
You can use the `ImFontGlyphRangesBuilder` helper to create glyph ranges based on text input. For example: for a game where your script is known, if you can feed your entire script to it and only build the characters the game needs.
|
||||
🆕 **Since 1.92, with an up to date backend: specifying glyph ranges is necessary, so this is not needed.**
|
||||
|
||||
:rewind: You can use the `ImFontGlyphRangesBuilder` helper to create glyph ranges based on text input. For example: for a game where your script is known, if you can feed your entire script to it and only build the characters the game needs.
|
||||
```cpp
|
||||
ImVector<ImWchar> ranges;
|
||||
ImFontGlyphRangesBuilder builder;
|
||||
@@ -309,10 +408,19 @@ io.Fonts->Build(); // Build the atlas while
|
||||
|
||||
## Using Custom Colorful Icons
|
||||
|
||||
🆕 **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 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).
|
||||
|
||||
:rewind: **Before 1.92:**
|
||||
|
||||
As an alternative to rendering colorful glyphs using imgui_freetype with `ImGuiFreeTypeBuilderFlags_LoadColor`, you may allocate your own space in the texture atlas and write yourself into it. **(This is a BETA api, use if you are familiar with dear imgui and with your rendering backend)**
|
||||
|
||||
- You can use the `ImFontAtlas::AddCustomRect()` and `ImFontAtlas::AddCustomRectFontGlyph()` api to register rectangles that will be packed into the font atlas texture. Register them before building the atlas, then call Build()`.
|
||||
- You can then use `ImFontAtlas::GetCustomRectByIndex(int)` to query the position/size of your rectangle within the texture, and blit/copy any graphics data of your choice into those rectangles.
|
||||
- You can then use `ImFontAtlas::GetCustomRect(int)` to query the position/size of your rectangle within the texture, and blit/copy any graphics data of your choice into those rectangles.
|
||||
- This API is beta because it is likely to change in order to support multi-dpi (multiple viewports on multiple monitors with varying DPI scale).
|
||||
|
||||
#### Pseudo-code:
|
||||
@@ -332,9 +440,7 @@ int tex_width, tex_height;
|
||||
io.Fonts->GetTexDataAsRGBA32(&tex_pixels, &tex_width, &tex_height);
|
||||
|
||||
for (int rect_n = 0; rect_n < IM_ARRAYSIZE(rect_ids); rect_n++)
|
||||
{
|
||||
int rect_id = rect_ids[rect_n];
|
||||
if (const ImFontAtlasCustomRect* rect = io.Fonts->GetCustomRectByIndex(rect_id))
|
||||
if (const ImTextureRect* rect = io.Fonts->GetCustomRect(rect_ids[rect_n]))
|
||||
{
|
||||
// Fill the custom rectangle with red pixels (in reality you would draw/copy your bitmap data here!)
|
||||
for (int y = 0; y < rect->Height; y++)
|
||||
@@ -344,7 +450,6 @@ for (int rect_n = 0; rect_n < IM_ARRAYSIZE(rect_ids); rect_n++)
|
||||
*p++ = IM_COL32(255, 0, 0, 255);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### [Return to Index](#index)
|
||||
|
||||
2
external/imgui/docs/README.md
vendored
2
external/imgui/docs/README.md
vendored
@@ -120,7 +120,7 @@ See the [Getting Started](https://github.com/ocornut/imgui/wiki/Getting-Started)
|
||||
|
||||
On most platforms and when using C++, **you should be able to use a combination of the [imgui_impl_xxxx](https://github.com/ocornut/imgui/tree/master/backends) backends without modification** (e.g. `imgui_impl_win32.cpp` + `imgui_impl_dx11.cpp`). If your engine supports multiple platforms, consider using more imgui_impl_xxxx files instead of rewriting them: this will be less work for you, and you can get Dear ImGui running immediately. You can _later_ decide to rewrite a custom backend using your custom engine functions if you wish so.
|
||||
|
||||
Integrating Dear ImGui within your custom engine is a matter of 1) wiring mouse/keyboard/gamepad inputs 2) uploading a texture to your GPU/render engine 3) providing a render function that can bind textures and render textured triangles, which is essentially what Backends are doing. The [examples/](https://github.com/ocornut/imgui/tree/master/examples) folder is populated with applications doing just that: setting up a window and using backends. If you follow the [Getting Started](https://github.com/ocornut/imgui/wiki/Getting-Started) guide it should in theory takes you less than an hour to integrate Dear ImGui. **Make sure to spend time reading the [FAQ](https://www.dearimgui.com/faq), comments, and the examples applications!**
|
||||
Integrating Dear ImGui within your custom engine is a matter of 1) wiring mouse/keyboard/gamepad inputs 2) uploading a texture to your GPU/render engine 3) providing a render function that can bind textures and render textured triangles, which is essentially what Backends are doing. The [examples/](https://github.com/ocornut/imgui/tree/master/examples) folder is populated with applications doing just that: setting up a window and using backends. If you follow the [Getting Started](https://github.com/ocornut/imgui/wiki/Getting-Started) guide it should in theory take you less than an hour to integrate Dear ImGui. **Make sure to spend time reading the [FAQ](https://www.dearimgui.com/faq), comments, and the examples applications!**
|
||||
|
||||
Officially maintained backends/bindings (in repository):
|
||||
- Renderers: DirectX9, DirectX10, DirectX11, DirectX12, Metal, OpenGL/ES/ES2, SDL_GPU, SDL_Renderer2/3, Vulkan, WebGPU.
|
||||
|
||||
17
external/imgui/docs/TODO.txt
vendored
17
external/imgui/docs/TODO.txt
vendored
@@ -26,9 +26,6 @@ It's mostly a bunch of personal notes, probably incomplete. Feel free to query i
|
||||
- window/size: manually triggered auto-fit (double-click on grip) shouldn't resize window down to viewport size?
|
||||
- window/size: how to allow to e.g. auto-size vertically to fit contents, but be horizontally resizable? Assuming SetNextWindowSize() is modified to treat -1.0f on each axis as "keep as-is" (would be good but might break erroneous code): Problem is UpdateWindowManualResize() and lots of code treat (window->AutoFitFramesX > 0 || window->AutoFitFramesY > 0) together.
|
||||
- window/opt: freeze window flag: if not focused/hovered, return false, render with previous ImDrawList. and/or reduce refresh rate. -> this may require enforcing that it is illegal to submit contents if Begin returns false.
|
||||
- window/child: background options for child windows, border option (disable rounding).
|
||||
- window/child: allow resizing of child windows (possibly given min/max for each axis?.)
|
||||
- window/child: allow SetNextWindowContentSize() to work on child windows.
|
||||
- window/clipping: some form of clipping when DisplaySize (or corresponding viewport) is zero.
|
||||
- window/tabbing: add a way to signify that a window or docked window requires attention (e.g. blinking title bar, trying to click behind a modal).
|
||||
- window/id_stack: add e.g. window->GetIDFromPath() with support for leading / and ../ (#1390, #331) -> model from test engine.
|
||||
@@ -272,22 +269,14 @@ It's mostly a bunch of personal notes, probably incomplete. Feel free to query i
|
||||
|
||||
- font: arbitrary line spacing. (#2945)
|
||||
- font: MergeMode: flags to select overwriting or not (this is now very easy with refactored ImFontAtlasBuildWithStbTruetype)
|
||||
- font: free the Alpha buffer if user only requested RGBA.
|
||||
!- font: better CalcTextSizeA() API, at least for simple use cases. current one is horrible (perhaps have simple vs extended versions).
|
||||
- font: better CalcTextSizeA() API, at least for simple use cases. current one is horrible (perhaps have simple vs extended versions).
|
||||
- font: for the purpose of RenderTextEllipsis(), it might be useful that CalcTextSizeA() can ignore the trailing padding?
|
||||
- font: a CalcTextHeight() helper could run faster than CalcTextSize().y
|
||||
- font: enforce monospace through ImFontConfig (for icons?) + create dual ImFont output from same input, reusing rasterized data but with different glyphs/AdvanceX
|
||||
- font: finish CustomRectRegister() to allow mapping Unicode codepoint to custom texture data
|
||||
- font: remove ID from CustomRect registration, it seems unnecessary!
|
||||
- font: make it easier to submit own bitmap font (same texture, another texture?). (#2127, #2575)
|
||||
- font: PushFontSize API (#1018)
|
||||
- font: MemoryTTF taking ownership confusing/not obvious, maybe default should be opposite?
|
||||
- font: storing MinAdvanceX per font would allow us to skip calculating line width (under a threshold of character count) in loops looking for block width
|
||||
- font/demo: add tools to show glyphs used by a text blob, display U16 value, list missing glyphs.
|
||||
- font/demo: demonstrate use of ImFontGlyphRangesBuilder.
|
||||
- font/atlas: add a missing Glyphs.reserve()
|
||||
- font/atlas: incremental updates
|
||||
- font/atlas: dynamic font atlas to avoid baking huge ranges into bitmap and make scaling easier.
|
||||
- font/draw: vertical and/or rotated text renderer (#705) - vertical is easier clipping wise
|
||||
- font/draw: need to be able to specify wrap start position.
|
||||
- font/draw: better reserve policy for large horizontal block of text (shouldn't reserve for all clipped lines). also see #3349.
|
||||
@@ -296,7 +285,6 @@ It's mostly a bunch of personal notes, probably incomplete. Feel free to query i
|
||||
- font: optimization: for monospace font (like the default one) we can trim IndexXAdvance as long as trailing value is == FallbackXAdvance (need to make sure TAB is still correct), would save on cache line.
|
||||
- font: add support for kerning, probably optional. A) perhaps default to (32..128)^2 matrix ~ 9K entries = 36KB, then hash for non-ascii?. B) or sparse lookup into per-char list?
|
||||
- font: add a simpler CalcTextSizeA() api? current one ok but not welcome if user needs to call it directly (without going through ImGui::CalcTextSize)
|
||||
- font: fix AddRemapChar() to work before atlas has been built.
|
||||
- font: (api breaking) remove "TTF" from symbol names. also because it now supports OTF.
|
||||
- font/opt: Considering storing standalone AdvanceX table as 16-bit fixed point integer?
|
||||
- font/opt: Glyph currently 40 bytes (2+9*4). Consider storing UV as 16-bits integer? (->32 bytes). X0/Y0/X1/Y1 as 16 fixed-point integers? Or X0/Y0 as float and X1/Y1 as fixed8_8?
|
||||
@@ -327,7 +315,7 @@ It's mostly a bunch of personal notes, probably incomplete. Feel free to query i
|
||||
- nav/windowing: Resizing window will currently fail with certain types of resizing constraints/callback applied
|
||||
- focus: preserve ActiveId/focus stack state, e.g. when opening a menu and close it, previously selected InputText() focus gets restored (#622)
|
||||
|
||||
- viewport: make it possible to have no main/hosting viewport
|
||||
- viewport: make it possible to have no main/hosting viewport (see #8268)
|
||||
- viewport: We set ImGuiViewportFlags_NoFocusOnAppearing in a way that is required for GLFW/SDL binding, but could be handled better without
|
||||
on a custom e.g. Win32 bindings. It prevents newly dragged-out viewports from taking the focus, which makes ALT+F4 more ambiguous.
|
||||
- viewport: not focusing newly undocked viewport means clicking back on previous one doesn't bring OS window to front.
|
||||
@@ -336,6 +324,7 @@ It's mostly a bunch of personal notes, probably incomplete. Feel free to query i
|
||||
- viewport: store per-viewport/monitor DPI in .ini file so an application reload or main window changing DPI on reload can be properly patched for.
|
||||
- viewport: implicit/fallback Debug window can hog a zombie viewport (harmless, noisy?) > could at least clear out the reference on a per session basis?
|
||||
- viewport: need to clarify how to use GetMousePos() from a user point of view.
|
||||
- viewport: could apply monitor boundaries to cliprect to coarse clip things out of monitor? (#8698)
|
||||
- platform: glfw: no support for ImGuiBackendFlags_HasMouseHoveredViewport.
|
||||
- platform: sdl: no support for ImGuiBackendFlags_HasMouseHoveredViewport. maybe we could use SDL_GetMouseFocus() / SDL_WINDOW_MOUSE_FOCUS if imgui could fallback on its heuristic when NoInputs is set
|
||||
- platform: sdl: no refresh of monitor/display (SDL doesn't seem to have an event for it).
|
||||
|
||||
Reference in New Issue
Block a user