Docs: Added FAQ entries removed old one which is misleading today. Misc tweaks.

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)
 

docs/README.md

@@ -96,7 +96,7 @@ Calling the `ImGui::ShowDemoWindow()` function will create a demo window showcas
 
 ![screenshot demo](https://raw.githubusercontent.com/wiki/ocornut/imgui/web/v167/v167-misc.png)
 
-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.
 

docs/TODO.txt

@@ -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.

examples/README.txt

@@ -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.
 

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