mirror of
https://github.com/ocornut/imgui.git
synced 2024-11-12 02:00:58 +01:00
Docs: Added FAQ entries removed old one which is misleading today. Misc tweaks.
This commit is contained in:
omar
parent
9c2a36f573
commit
99f68d7958
20
docs/FAQ.md
20
docs/FAQ.md
@ -15,12 +15,13 @@ or view this file with any Markdown viewer.
|
||||
| [What is this library called?](#q-what-is-this-library-called) |
|
||||
| [Which version should I get?](#q-which-version-should-i-get) |
|
||||
| **Q&A: Integration** |
|
||||
| **[How to get started?](#q-how-to-get-started)** |
|
||||
| **[How can I tell whether to dispatch mouse/keyboard to Dear ImGui or to my application?](#q-how-can-i-tell-whether-to-dispatch-mousekeyboard-to-dear-imgui-or-to-my-application)** |
|
||||
| [How can I enable keyboard or gamepad controls?](#q-how-can-i-enable-keyboard-or-gamepad-controls) |
|
||||
| [How can I use this on a machine without mouse, keyboard or screen? (input share, remote display)](#q-how-can-i-use-this-on-a-machine-without-mouse-keyboard-or-screen-input-share-remote-display) |
|
||||
| [I integrated Dear ImGui in my engine and the text or lines are blurry..](#q-i-integrated-dear-imgui-in-my-engine-and-the-text-or-lines-are-blurry) |
|
||||
| [I integrated Dear ImGui in my engine and little squares are showing instead of text..](#q-i-integrated-dear-imgui-in-my-engine-and-little-squares-are-showing-instead-of-text) |
|
||||
| [I integrated Dear ImGui in my engine and some elements are clipping or disappearing when I move windows around..](#q-i-integrated-dear-imgui-in-my-engine-and-some-elements-are-clipping-or-disappearing-when-i-move-windows-around) |
|
||||
| [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)
|
||||
| [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** |
|
||||
| **[Why are multiple widgets reacting when I interact with a single one?<br>How can I have multiple widgets with the same label or with an empty label?](#q-why-are-multiple-widgets-reacting-when-i-interact-with-a-single-one-q-how-can-i-have-multiple-widgets-with-the-same-label-or-with-an-empty-label)** |
|
||||
| [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)|
|
||||
@ -88,6 +89,15 @@ You may merge in the [tables](https://github.com/ocornut/imgui/tree/tables) bran
|
||||
|
||||
# Q&A: Integration
|
||||
|
||||
### Q: How to get started?
|
||||
|
||||
Read `PROGRAMMER GUIDE` section of [imgui.cpp](https://github.com/ocornut/imgui/blob/master/imgui.cpp).
|
||||
Read [examples/README.txt](https://github.com/ocornut/imgui/tree/master/examples/README.txt).
|
||||
|
||||
##### [Return to Index](#index)
|
||||
|
||||
---
|
||||
|
||||
### Q: How can I tell whether to dispatch mouse/keyboard to Dear ImGui or to my application?
|
||||
|
||||
You can read the `io.WantCaptureMouse`, `io.WantCaptureKeyboard` and `io.WantTextInput` flags from the ImGuiIO structure.
|
||||
@ -139,9 +149,9 @@ Console SDK also sometimes provide equivalent tooling or wrapper for Synergy-lik
|
||||
|
||||
---
|
||||
|
||||
### Q: I integrated Dear ImGui in my engine and the text or lines are blurry..
|
||||
In your Render function, try translating your projection matrix by (0.5f,0.5f) or (0.375f,0.375f).
|
||||
Also make sure your orthographic projection matrix and io.DisplaySize matches your actual framebuffer dimension.
|
||||
### Q: I integrated Dear ImGui in my engine and little squares are showing instead of text..
|
||||
This usually means that: your font texture wasn't uploaded into GPU, or your shader or other rendering state are not reading from the right texture (e.g. texture wasn't bound).
|
||||
If this happens using the standard back-ends it is probably that the texture failed to upload, which could happens if for some reason your texture is too big. Also see [docs/FONTS.md](https://github.com/ocornut/imgui/blob/master/docs/FONTS.md).
|
||||
|
||||
##### [Return to Index](#index)
|
||||
|
||||
|
||||
@ -96,7 +96,7 @@ Calling the `ImGui::ShowDemoWindow()` function will create a demo window showcas
|
||||
|
||||
|
||||
|
||||
You should be able to build the examples from sources (tested on Windows/Mac/Linux). If you don't, let me know! If you want to have a quick look at some Dear ImGui features, you can download Windows binaries of the demo app here:
|
||||
You should be able to build the examples from sources (tested on Windows/Mac/Linux). If you don't, let us know! If you want to have a quick look at some Dear ImGui features, you can download Windows binaries of the demo app here:
|
||||
- [imgui-demo-binaries-20190715.zip](http://www.dearimgui.org/binaries/imgui-demo-binaries-20200412.zip) (Windows binaries, 1.76, built 2020/04/12, master branch) or [older demo binaries](http://www.dearimgui.org/binaries).
|
||||
|
||||
The demo applications are not DPI aware so expect some blurriness on a 4K screen. For DPI awareness in your application, you can load/reload your font at different scale, and scale your style with `style.ScaleAllSizes()` (see [FAQ](https://www.dearimgui.org/faq)).
|
||||
@ -158,7 +158,7 @@ Private support is available for paying business customers (E-mail: _contact @ d
|
||||
|
||||
**Which version should I get?**
|
||||
|
||||
I occasionally tag [Releases](https://github.com/ocornut/imgui/releases) but it is generally safe and recommended to sync to master/latest. The library is fairly stable and regressions tend to be fixed fast when reported.
|
||||
We occasionally tag [Releases](https://github.com/ocornut/imgui/releases) but it is generally safe and recommended to sync to master/latest. The library is fairly stable and regressions tend to be fixed fast when reported.
|
||||
|
||||
You may also peak at the [Multi-Viewport](https://github.com/ocornut/imgui/issues/1542) and [Docking](https://github.com/ocornut/imgui/issues/2109) features in the `docking` branch. Many projects are using this branch and it is kept in sync with master regularly.
|
||||
|
||||
|
||||
@ -382,6 +382,7 @@ It's mostly a bunch of personal notes, probably incomplete. Feel free to query i
|
||||
- examples: window minimize, maximize (#583)
|
||||
- examples: provide a zero frame-rate/idle example.
|
||||
- examples: dx11/dx12: try to use new swapchain blit models (#2970)
|
||||
- backends: report it better when not able to create texture?
|
||||
- backends: apple: example_apple should be using modern GL3.
|
||||
- backends: glfw: could go idle when minimized? if (glfwGetWindowAttrib(window, GLFW_ICONIFIED)) { glfwWaitEvents(); continue; } // issue: DeltaTime will be super high on resume, perhaps provide a way to let impl know (#440)
|
||||
- backends: opengl: rename imgui_impl_opengl2 to impl_opengl_legacy and imgui_impl_opengl3 to imgui_impl_opengl? (#1900)
|
||||
@ -392,7 +393,7 @@ It's mostly a bunch of personal notes, probably incomplete. Feel free to query i
|
||||
- backends: bgfx: https://gist.github.com/RichardGale/6e2b74bc42b3005e08397236e4be0fd0
|
||||
- backends: mscriptem: with refactored examples, we could provide a direct imgui_impl_emscripten platform layer (see eg. https://github.com/floooh/sokol-samples/blob/master/html5/imgui-emsc.cc#L42)
|
||||
|
||||
- optimization: replace vsnprintf with stb_printf? or enable the defines/infrastructure to allow it (#1038)
|
||||
- optimization: replace vsnprintf with stb_printf? using IMGUI_USE_STB_SPRINTF.(#1038)
|
||||
- optimization: add clipping for multi-component widgets (SliderFloatX, ColorEditX, etc.). one problem is that nav branch can't easily clip parent group when there is a move request.
|
||||
- optimization: add a flag to disable most of rendering, for the case where the user expect to skip it (#335)
|
||||
- optimization: fully covered window (covered by another with non-translucent bg + WindowRounding worth of padding) may want to clip rendering.
|
||||
|
||||
@ -32,29 +32,34 @@ You can find binaries of some of those example applications at:
|
||||
|
||||
|
||||
---------------------------------------
|
||||
MISC COMMENTS AND SUGGESTIONS
|
||||
GETTING STARTED
|
||||
---------------------------------------
|
||||
|
||||
- Read FAQ at http://dearimgui.org/faq
|
||||
|
||||
- Please read 'PROGRAMMER GUIDE' in imgui.cpp for notes on how to setup Dear ImGui in your codebase.
|
||||
Please read the comments and instruction at the top of each file.
|
||||
Please read FAQ at http://www.dearimgui.org/faq
|
||||
|
||||
- If you are using of the backend provided here, so you can copy the imgui_impl_xxx.cpp/h files
|
||||
- If you are using of the backend provided here, you can add the imgui_impl_xxx.cpp/h files
|
||||
to your project and use them unmodified. Each imgui_impl_xxxx.cpp comes with its own individual
|
||||
ChangeLog at the top of the .cpp files, so if you want to update them later it will be easier to
|
||||
Changelog at the top of the .cpp files, so if you want to update them later it will be easier to
|
||||
catch up with what changed.
|
||||
|
||||
- Dear ImGui has 0 to 1 frame of lag for most behaviors, at 60 FPS your experience should be pleasant.
|
||||
However, consider that OS mouse cursors are typically drawn through a specific hardware accelerated path
|
||||
and will feel smoother than common GPU rendered contents (including Dear ImGui windows).
|
||||
You may experiment with the io.MouseDrawCursor flag to request Dear ImGui to draw a mouse cursor itself,
|
||||
to visualize the lag between a hardware cursor and a software cursor. However, rendering a mouse cursor
|
||||
at 60 FPS will feel slow. It might be beneficial to the user experience to switch to a software rendered
|
||||
cursor only when an interactive drag is in progress.
|
||||
Note that some setup or GPU drivers are likely to be causing extra lag depending on their settings.
|
||||
If you feel that dragging windows feels laggy and you are not sure who to blame: try to build an
|
||||
application drawing a shape directly under the mouse cursor.
|
||||
- Dear ImGui has no particular extra lag for most behaviors, e.g. the value of 'io.MousePos' provided in
|
||||
NewFrame() will result at the time of EndFrame()/Render() in a moved windows rendered following that mouse
|
||||
movement. At 60 FPS your experience should be pleasant.
|
||||
However, consider that OS mouse cursors are typically drawn through a very specific hardware accelerated
|
||||
path and will feel smoother than the majority of contents rendererd via regular graphics API (including,
|
||||
but not limited to Dear ImGui windows). Because UI rendering and interaction happens on the same plane as
|
||||
the mouse, that disconnect may be jarring to particularly sensitive users.
|
||||
You may experiment with enabling the io.MouseDrawCursor flag to request Dear ImGui to draw a mouse cursor
|
||||
using the regular graphics API, to help you visualize the difference between a "hardware" cursor and a
|
||||
regularly rendered software cursor.
|
||||
However, rendering a mouse cursor at 60 FPS will feel sluggish so you likely won't want to enable that at
|
||||
all times. It might be beneficial for the user experience to switch to a software rendered cursor _only_
|
||||
when an interactive drag is in progress.
|
||||
Note that some setup or GPU drivers are likely to be causing extra display lag depending on their settings.
|
||||
If you feel that dragging windows feels laggy and you are not sure what the cause is: try to build a simple
|
||||
drawing a flat 2D shape directly under the mouse cursor.
|
||||
|
||||
|
||||
---------------------------------------
|
||||
@ -155,12 +160,12 @@ Those will allow you to create portable applications and will solve and abstract
|
||||
Building:
|
||||
Unfortunately in 2020 it is still tedious to create and maintain portable build files using external
|
||||
libraries (the kind we're using here to create a window and render 3D triangles) without relying on
|
||||
third party software. For most examples here I choose to provide:
|
||||
third party software. For most examples here we choose to provide:
|
||||
- Makefiles for Linux/OSX
|
||||
- Batch files for Visual Studio 2008+
|
||||
- A .sln project file for Visual Studio 2010+
|
||||
- A .sln project file for Visual Studio 2012+
|
||||
- Xcode project files for the Apple examples
|
||||
Please let me know if they don't work with your setup!
|
||||
Please let us know if they don't work with your setup!
|
||||
You can probably just import the imgui_impl_xxx.cpp/.h files into your own codebase or compile those
|
||||
directly with a command-line compiler.
|
||||
|
||||
|
||||
11
imgui.cpp
11
imgui.cpp
@ -18,7 +18,7 @@
|
||||
|
||||
// Developed by Omar Cornut and every direct or indirect contributors to the GitHub.
|
||||
// See LICENSE.txt for copyright and licensing details (standard MIT License).
|
||||
// This library is free but I need your support to sustain development and maintenance.
|
||||
// This library is free but needs your support to sustain development and maintenance.
|
||||
// Businesses: you can support continued development via invoiced technical support, maintenance and sponsoring contracts. Please reach out to "contact AT dearimgui.org".
|
||||
// Individuals: you can support continued development via donations. See docs/README or web page.
|
||||
|
||||
@ -169,7 +169,7 @@ CODE
|
||||
---------------------------------------------------------------
|
||||
- Run and study the examples and demo in imgui_demo.cpp to get acquainted with the library.
|
||||
- In the majority of cases you should be able to use unmodified back-ends files available in the examples/ folder.
|
||||
- Add the Dear ImGui source files to your projects or using your preferred build system.
|
||||
- Add the Dear ImGui source files + selected back-end source files to your projects or using your preferred build system.
|
||||
It is recommended you build and statically link the .cpp files as part of your project and NOT as shared library (DLL).
|
||||
- You can later customize the imconfig.h file to tweak some compile-time behavior, such as integrating Dear ImGui types with your own maths types.
|
||||
- When using Dear ImGui, your programming IDE is your friend: follow the declaration of variables, functions and types to find comments about them.
|
||||
@ -622,18 +622,21 @@ CODE
|
||||
Q: What is this library called?
|
||||
Q: Which version should I get?
|
||||
>> This library is called "Dear ImGui", please don't call it "ImGui" :)
|
||||
>> See https://www.dearimgui.org/faq
|
||||
>> See https://www.dearimgui.org/faq for details.
|
||||
|
||||
Q&A: Integration
|
||||
================
|
||||
|
||||
Q: How to get started?
|
||||
A: Read 'PROGRAMMER GUIDE' above. Read examples/README.txt.
|
||||
|
||||
Q: How can I tell whether to dispatch mouse/keyboard to Dear ImGui or to my application?
|
||||
A: You should read the 'io.WantCaptureMouse', 'io.WantCaptureKeyboard' and 'io.WantTextInput' flags!
|
||||
>> See https://www.dearimgui.org/faq for fully detailed answer. You really want to read this.
|
||||
|
||||
Q. How can I enable keyboard controls?
|
||||
Q: How can I use this without a mouse, without a keyboard or without a screen? (gamepad, input share, remote display)
|
||||
Q: I integrated Dear ImGui in my engine and the text or lines are blurry..
|
||||
Q: I integrated Dear ImGui in my engine and little squares are showing instead of text..
|
||||
Q: I integrated Dear ImGui in my engine and some elements are clipping or disappearing when I move windows around..
|
||||
Q: I integrated Dear ImGui in my engine and some elements are displaying outside their expected windows boundaries..
|
||||
>> See https://www.dearimgui.org/faq
|
||||
|
||||
Loading…
Reference in New Issue
Block a user