mirror/imgui
1
0
Fork 0
mirror of https://github.com/ocornut/imgui.git synced 2026-01-30 03:10:06 +00:00
Code Activity

Merge branch 'master' into docking

Browse source 
# Conflicts:
#	backends/imgui_impl_dx11.cpp
#	backends/imgui_impl_dx11.h
#	backends/imgui_impl_dx12.cpp
#	backends/imgui_impl_dx12.h
#	backends/imgui_impl_glfw.cpp
#	backends/imgui_impl_sdlrenderer2.cpp
#	backends/imgui_impl_sdlrenderer2.h
#	backends/imgui_impl_sdlrenderer3.cpp
#	backends/imgui_impl_sdlrenderer3.h
#	backends/imgui_impl_vulkan.cpp
#	backends/imgui_impl_vulkan.h
#	backends/imgui_impl_wgpu.cpp
#	backends/imgui_impl_wgpu.h
#	backends/imgui_impl_win32.cpp
#	imgui.cpp
#	imgui_demo.cpp
This commit is contained in:
ocornut 2024-10-14 19:20:55 +02:00
commit 514a97a9b7
38 changed files with 319 additions and 167 deletions
Download patch file Download diff file Expand all files Collapse all files

50
docs/CHANGELOG.txt
View file

@ -36,20 +36,61 @@ HOW TO UPDATE?
- Please report any issue!
-----------------------------------------------------------------------
VERSION 1.91.4 WIP
VERSION 1.91.4 WIP (In Progress)
-----------------------------------------------------------------------
Breaking changes:
- The typedef for ImTextureID now defaults to ImU64 instead of void*. (#1641)
- This removes the requirement to redefine it for backends which are e.g. storing
descriptor sets or other 64-bits structures when building on 32-bits archs.
It therefore simplify various building scripts/helpers.
- You may have compile-time issues if you were casting to 'void*' instead of 'ImTextureID'
when passing your types to functions taking ImTextureID values, e.g. ImGui::Image().
In doubt it is almost always better to do an intermediate intptr_t cast, since it
allows casting any pointer/integer type without warning:
- May warn: ImGui::Image((void*)MyTextureData, ...);
- May warn: ImGui::Image((void*)(intptr_t)MyTextureData, ...);
- Won't warn: ImGui::Image((ImTextureID)(intptr_t)MyTextureData), ...);
- Note that you can always define ImTextureID to be your own high-level structures
(with dedicated constructors) if you like.
- IO: moved ImGuiConfigFlags_NavEnableSetMousePos to standalone io.ConfigNavMoveSetMousePos bool.
- IO: moved ImGuiConfigFlags_NavNoCaptureKeyboard to standalone io.ConfigNavCaptureKeyboard bool
(note the inverted value!). (#2517, #2009)
Kept legacy names (will obsolete) + code that copies settings once the first time.
Dynamically changing the old value won't work. Switch to using the new value!
Other changes:
- IO: added 'void* platform_io.Renderer_RenderState' which is set during the
ImGui_ImplXXXX_RenderDrawData() of standard backend to expose selected render
state to draw callbacks. (#6969, #5834, #7468, #3590)
- Backends: DX11, DX12, Vulkan, WGPU: expose selected state in ImGui_ImplXXXX_RenderState.
structure during render loop. (#6969, #5834, #7468, #3590)
- IO: WantCaptureKeyboard is never set when ImGuiConfigFlags_NoKeyboard is enabled. (#4921)
- Error Handling: turned a few more functions into recoverable errors. (#1651)
- Nav: added io.ConfigNavEscapeClearFocusWindow to clear focused window on Escape. (#3200)
- Nav: pressing escape to hide nav highlight doesn't clear location from when ctrl+tabbing
back into same window later.
- Nav: fixed Ctrl+Tab so when starting with no focused window it starts from the top-most
window. (#3200)
- Nav: rectangle highlight not rendered for items with ImGuiItemFlags_NoNav. Can be relevant
when e.g activating the item with mouse, then ctrl+tabbing back and forth.
- DrawList: AddCallback() added an optional size parameter allowing to copy and
store any amount of user data for usage by callbacks: (#6969, #4770, #7665)
- If userdata_size == 0: we copy/store the 'userdata' argument as-is (existing behavior).
It will be available unmodified in ImDrawCmd::UserCallbackData during render.
- If userdata_size > 0, we copy/store 'userdata_size' bytes pointed to by 'userdata' (new behavior).
We store them in a buffer stored inside the drawlist. ImDrawCmd::UserCallbackData
will point inside that buffer so you have to retrieve data from there. Your callback
may need to use ImDrawCmd::UserCallbackDataSize if you expect dynamically-sized data.
- Tables: fixed initial auto-sizing issue with synched-instances. (#8045, #7218)
- InputText: fixed an issue with not declaring ownership of Delete/Backspace/Arrow keys,
preventing use of external shortcuts not guarded by an ActiveId check. (#8048) [@geertbleyen]
- InputText: ensure mouse cursor shape is set regardless of whether keyboard mode is
enabled or not. (#6417)
- Backends: DX11, DX12, SDLRenderer2/3. Vulkan, WGPU: expose selected state in
ImGui_ImplXXXX_RenderState structures during render loop. (#6969, #5834, #7468, #3590)
- Backends: DX9, DX10, DX11, DX12, OpenGL, Vulkan, WGPU: Changed default texture sampler
to Clamp instead of Repeat/Wrap. (#7468, #7511, #5999, #5502)
to Clamp instead of Repeat/Wrap. (#7468, #7511, #5999, #5502, #7230)
Docking+Viewports Branch:
@ -499,6 +540,7 @@ Other changes:
which was pressed over void/underlying app, which is consistent/needed to allow the
mouse up event of a drag over void/underlying app to catch release. (#1392) [@Moka42]
- IO: Added io.ClearInputMouse() to clear mouse state. (#4921)
- IO: Added ImGuiConfigFlags_NoKeyboard for consistency and convenience. (#4921)
- Windows: BeginChild(): fixed a glitch when during a resize of a child window which is
tightly close to the boundaries of its parent (e.g. with zero WindowPadding), the child
position could have temporarily be moved around by erroneous padding application. (#7706)

39
docs/FAQ.md
View file

@ -380,8 +380,9 @@ node open/closed state differently. See what makes more sense in your situation!
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 ImTextureID (void*) value.
- Loading image files from the disk and turning them into a texture is not within the scope of Dear ImGui (for a good reason).
- 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.
**Please read documentations or tutorials on your graphics API to understand how to display textures on the screen before moving onward.**
@ -389,27 +390,27 @@ 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.
ImTextureID is nothing more than a void*, aka 4/8 bytes worth of data: just enough to store one pointer or integer of your choice.
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.
- 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:
- ImTextureID = GLuint
- ImTextureID should contains 'GLuint' (GL texture identifier).
- See ImGui_ImplOpenGL3_RenderDrawData() function in imgui_impl_opengl3.cpp
```
```cpp
DirectX9:
- ImTextureID = LPDIRECT3DTEXTURE9
- ImTextureID should contain a 'LPDIRECT3DTEXTURE9' (pointer).
- See ImGui_ImplDX9_RenderDrawData() function in imgui_impl_dx9.cpp
```
```cpp
DirectX11:
- ImTextureID = ID3D11ShaderResourceView*
- ImTextureID should contain a 'ID3D11ShaderResourceView*' (poiter)
- See ImGui_ImplDX11_RenderDrawData() function in imgui_impl_dx11.cpp
```
```cpp
DirectX12:
- ImTextureID = D3D12_GPU_DESCRIPTOR_HANDLE
- ImTextureID should contain a 'D3D12_GPU_DESCRIPTOR_HANDLE' (always 64-bits)
- See ImGui_ImplDX12_RenderDrawData() function in imgui_impl_dx12.cpp
```
For example, in the OpenGL example backend we store raw OpenGL texture identifier (GLuint) inside ImTextureID.
@ -421,14 +422,14 @@ If you are starting with OpenGL or DirectX or Vulkan and haven't built much of a
User code may do:
```cpp
// Cast our texture type to ImTextureID / void*
// Cast our texture type to ImTextureID
MyTexture* texture = g_CoffeeTableTexture;
ImGui::Image((void*)texture, ImVec2(texture->Width, texture->Height));
ImGui::Image((ImTextureID)(intptr_t)texture, ImVec2(texture->Width, texture->Height));
```
The renderer function called after ImGui::Render() will receive that same value that the user code passed:
```cpp
// Cast ImTextureID / void* stored in the draw command as our texture type
MyTexture* texture = (MyTexture*)pcmd->GetTexID();
// Cast ImTextureID stored in the draw command as our texture type
MyTexture* texture = (MyTexture*)(intptr_t)pcmd->GetTexID();
MyEngineBindTexture2D(texture);
```
Once you understand this design, you will understand that loading image files and turning them into displayable textures is not within the scope of Dear ImGui.
@ -437,19 +438,19 @@ If you want to display an image file (e.g. PNG file) on the screen, please refer
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) to find simplified examples for loading textures with OpenGL, DirectX9 and DirectX11.
C/C++ tip: a void* is pointer-sized storage. You may safely store any pointer or integer into it by casting your value to ImTextureID / void*, and vice-versa.
Because both end-points (user code and rendering function) are under your control, you know exactly what is stored inside the ImTextureID / void*.
C/C++ tip: a u64 is 8 bytes. You may safely store any pointer or integer into it by casting your value to ImTextureID, and vice-versa.
Because both end-points (user code and rendering function) are under your control, you know exactly what is stored inside the ImTextureID.
Here are some examples:
```cpp
GLuint my_tex = XXX;
void* my_void_ptr;
my_void_ptr = (void*)(intptr_t)my_tex; // cast a GLuint into a void* (we don't take its address! we literally store the value inside the pointer)
my_tex = (GLuint)(intptr_t)my_void_ptr; // cast a void* into a GLuint
ImTextureID my_imtexid;
my_imtexid = (ImTextureID)(intptr_t)my_tex; // cast a GLuint into a ImTextureID (we don't take its address! we just copy the address)
my_tex = (GLuint)(intptr_t)my_imtexid; // cast a ImTextureID into a GLuint
ID3D11ShaderResourceView* my_dx11_srv = XXX;
void* my_void_ptr;
my_void_ptr = (void*)my_dx11_srv; // cast a ID3D11ShaderResourceView* into an opaque void*
my_dx11_srv = (ID3D11ShaderResourceView*)my_void_ptr; // cast a void* into a ID3D11ShaderResourceView*
ImTextureID my_imtexid;
my_imtexid = (ImTextureID)(intptr_t)my_dx11_srv; // cast a ID3D11ShaderResourceView* into an opaque ImTextureID
my_dx11_srv = (ID3D11ShaderResourceView*)(intptr_t)_my_imtexid; // cast a ImTextureID into a ID3D11ShaderResourceView*
```
Finally, you may call `ImGui::ShowMetricsWindow()` to explore/visualize/understand how the ImDrawList are generated.

2
docs/README.md
View file

@ -196,7 +196,7 @@ Ongoing Dear ImGui development is and has been financially supported by users an
**THANK YOU to all past and present supporters for helping to keep this project alive and thriving!**
Dear ImGui is using software and services provided free of charge for open source projects:
- [PVS-Studio](https://www.viva64.com/en/b/0570/) for static analysis.
- [PVS-Studio](https://pvs-studio.com/en/pvs-studio/?utm_source=website&utm_medium=github&utm_campaign=open_source) for static analysis (supports C/C++/C#/Java).
- [GitHub actions](https://github.com/features/actions) for continuous integration systems.
- [OpenCppCoverage](https://github.com/OpenCppCoverage/OpenCppCoverage) for code coverage analysis.

5
docs/TODO.txt
View file

@ -9,8 +9,7 @@ It's mostly a bunch of personal notes, probably incomplete. Feel free to query i
- doc: add a proper documentation system (maybe relying on automation? #435)
- doc: checklist app to verify backends/integration of imgui (test inputs, rendering, callback, etc.).
- doc/tips: tips of the day: website? applet in imgui_club?
- doc/wiki: work on the wiki https://github.com/ocornut/imgui/wiki
- window: preserve/restore relative focus ordering (persistent or not), and e.g. of multiple reappearing windows (#2304) -> also see docking reference to same #.
- window: calling SetNextWindowSize() every frame with <= 0 doesn't do anything, may be useful to allow (particularly when used for a single axis). (#690)
- window: add a way for very transient windows (non-saved, temporary overlay over hundreds of objects) to "clean" up from the global window list. perhaps a lightweight explicit cleanup pass.
@ -44,7 +43,7 @@ It's mostly a bunch of personal notes, probably incomplete. Feel free to query i
- drawlist: maintaining bounding box per command would allow to merge draw command when clipping isn't relied on (typical non-scrolling window or non-overflowing column would merge with previous command). (WIP branch)
- drawlist: make it easier to toggle AA per primitive, so we can use e.g. non-AA fill + AA borders more naturally
- drawlist: non-AA strokes have gaps between points (#593, #288), glitch especially on RenderCheckmark() and ColorPicker4().
- drawlist: callback: add an extra void* in ImDrawCallback to allow passing render-local data to the callback (would break API).
- drawlist: callback: add an extra void* in ImDrawCallback to expose render state instead of pulling from Renderer_RenderState (would break API).
- drawlist: AddRect vs AddLine position confusing (#2441)
- drawlist/opt: store rounded corners in texture to use 1 quad per corner (filled and wireframe) to lower the cost of rounding. (#1962)
- drawlist/opt: AddRect() axis aligned pixel aligned (no-aa) could use 8 triangles instead of 16 and no normal calculation.