|
|
@@ -16,6 +16,7 @@
|
|
|
// - Getting Started https://github.com/ocornut/imgui/wiki/Getting-Started
|
|
|
// - Glossary https://github.com/ocornut/imgui/wiki/Glossary
|
|
|
// - Issues & support https://github.com/ocornut/imgui/issues
|
|
|
+// - Tests & Automation https://github.com/ocornut/imgui_test_engine
|
|
|
|
|
|
// Getting Started?
|
|
|
// - Read https://github.com/ocornut/imgui/wiki/Getting-Started
|
|
|
@@ -25,8 +26,9 @@
|
|
|
// 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 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.com".
|
|
|
-// Individuals: you can support continued development via donations. See docs/README or web page.
|
|
|
+// Businesses: you can support continued development via B2B invoiced technical support, maintenance and sponsoring contracts.
|
|
|
+// PLEASE reach out at contact AT dearimgui DOT com. See https://github.com/ocornut/imgui/wiki/Sponsors
|
|
|
+// Businesses: you can also purchase licenses for the Dear ImGui Automation/Test Engine.
|
|
|
|
|
|
// It is recommended that you don't modify imgui.cpp! It will become difficult for you to update the library.
|
|
|
// Note that 'ImGui::' being a namespace, you can add functions into the namespace from your own source files, without
|
|
|
@@ -109,9 +111,10 @@ CODE
|
|
|
- Portable, minimize dependencies, run on target (consoles, phones, etc.).
|
|
|
- Efficient runtime and memory consumption.
|
|
|
|
|
|
- Designed for developers and content-creators, not the typical end-user! Some of the current weaknesses includes:
|
|
|
+ Designed primarily for developers and content-creators, not the typical end-user!
|
|
|
+ Some of the current weaknesses (which we aim to address in the future) includes:
|
|
|
|
|
|
- - Doesn't look fancy, doesn't animate.
|
|
|
+ - Doesn't look fancy.
|
|
|
- Limited layout features, intricate layouts are typically crafted in code.
|
|
|
|
|
|
|
|
|
@@ -190,9 +193,11 @@ CODE
|
|
|
READ FIRST
|
|
|
----------
|
|
|
- Remember to check the wonderful Wiki (https://github.com/ocornut/imgui/wiki)
|
|
|
- - Your code creates the UI, if your code doesn't run the UI is gone! The UI can be highly dynamic, there are no construction or
|
|
|
- destruction steps, less superfluous data retention on your side, less state duplication, less state synchronization, fewer bugs.
|
|
|
+ - Your code creates the UI every frame of your application loop, if your code doesn't run the UI is gone!
|
|
|
+ The UI can be highly dynamic, there are no construction or destruction steps, less superfluous
|
|
|
+ data retention on your side, less state duplication, less state synchronization, fewer bugs.
|
|
|
- Call and read ImGui::ShowDemoWindow() for demo code demonstrating most features.
|
|
|
+ Or browse https://pthom.github.io/imgui_manual_online/manual/imgui_manual.html for interactive web version.
|
|
|
- The library is designed to be built from sources. Avoid pre-compiled binaries and packaged versions. See imconfig.h to configure your build.
|
|
|
- Dear ImGui is an implementation of the IMGUI paradigm (immediate-mode graphical user interface, a term coined by Casey Muratori).
|
|
|
You can learn about IMGUI principles at http://www.johno.se/book/imgui.html, http://mollyrocket.com/861 & more links in Wiki.
|
|
|
@@ -200,18 +205,38 @@ CODE
|
|
|
For every application frame, your UI code will be called only once. This is in contrast to e.g. Unity's implementation of an IMGUI,
|
|
|
where the UI code is called multiple times ("multiple passes") from a single entry point. There are pros and cons to both approaches.
|
|
|
- Our origin is on the top-left. In axis aligned bounding boxes, Min = top-left, Max = bottom-right.
|
|
|
- - This codebase is also optimized to yield decent performances with typical "Debug" builds settings.
|
|
|
- Please make sure you have asserts enabled (IM_ASSERT redirects to assert() by default, but can be redirected).
|
|
|
If you get an assert, read the messages and comments around the assert.
|
|
|
- - C++: this is a very C-ish codebase: we don't rely on C++11, we don't include any C++ headers, and ImGui:: is a namespace.
|
|
|
- - C++: ImVec2/ImVec4 do not expose math operators by default, because it is expected that you use your own math types.
|
|
|
- See FAQ "How can I use my own math types instead of ImVec2/ImVec4?" for details about setting up imconfig.h for that.
|
|
|
- However, imgui_internal.h can optionally export math operators for ImVec2/ImVec4, which we use in this codebase.
|
|
|
- - C++: pay attention that ImVector<> manipulates plain-old-data and does not honor construction/destruction (avoid using it in your code!).
|
|
|
+ - This codebase aims to be highly optimized:
|
|
|
+ - A typical idle frame should never call malloc/free.
|
|
|
+ - We rely on a maximum of constant-time or O(N) algorithms. Limiting searches/scans as much as possible.
|
|
|
+ - We put particular energy in making sure performances are decent with typical "Debug" build settings as well.
|
|
|
+ Which mean we tend to avoid over-relying on "zero-cost abstraction" as they aren't zero-cost at all.
|
|
|
+ - This codebase aims to be both highly opinionated and highly flexible:
|
|
|
+ - This code works because of the things it choose to solve or not solve.
|
|
|
+ - C++: this is a pragmatic C-ish codebase: we don't use fancy C++ features, we don't include C++ headers,
|
|
|
+ and ImGui:: is a namespace. We rarely use member functions (and when we did, I am mostly regretting it now).
|
|
|
+ This is to increase compatibility, increase maintainability and facilitate use from other languages.
|
|
|
+ - C++: ImVec2/ImVec4 do not expose math operators by default, because it is expected that you use your own math types.
|
|
|
+ See FAQ "How can I use my own math types instead of ImVec2/ImVec4?" for details about setting up imconfig.h for that.
|
|
|
+ We can can optionally export math operators for ImVec2/ImVec4 using IMGUI_DEFINE_MATH_OPERATORS, which we use internally.
|
|
|
+ - C++: pay attention that ImVector<> manipulates plain-old-data and does not honor construction/destruction
|
|
|
+ (so don't use ImVector in your code or at our own risk!).
|
|
|
+ - Building: We don't use nor mandate a build system for the main library.
|
|
|
+ This is in an effort to ensure that it works in the real world aka with any esoteric build setup.
|
|
|
+ This is also because providing a build system for the main library would be of little-value.
|
|
|
+ The build problems are almost never coming from the main library but from specific backends.
|
|
|
|
|
|
|
|
|
HOW TO UPDATE TO A NEWER VERSION OF DEAR IMGUI
|
|
|
----------------------------------------------
|
|
|
+ - Update submodule or copy/overwrite every file.
|
|
|
+ - About imconfig.h:
|
|
|
+ - You may modify your copy of imconfig.h, in this case don't overwrite it.
|
|
|
+ - or you may locally branch to modify imconfig.h and merge/rebase latest.
|
|
|
+ - or you may '#define IMGUI_USER_CONFIG "my_config_file.h"' globally from your build system to
|
|
|
+ specify a custom path for your imconfig.h file and instead not have to modify the default one.
|
|
|
+
|
|
|
- Overwrite all the sources files except for imconfig.h (if you have modified your copy of imconfig.h)
|
|
|
- Or maintain your own branch where you have imconfig.h modified as a top-most commit which you can regularly rebase over "master".
|
|
|
- You can also use '#define IMGUI_USER_CONFIG "my_config_file.h" to redirect configuration to your own file.
|
|
|
@@ -220,11 +245,12 @@ CODE
|
|
|
from the public API. If you have a problem with a missing function/symbols, search for its name in the code, there will
|
|
|
likely be a comment about it. Please report any issue to the GitHub page!
|
|
|
- To find out usage of old API, you can add '#define IMGUI_DISABLE_OBSOLETE_FUNCTIONS' in your configuration file.
|
|
|
- - Try to keep your copy of Dear ImGui reasonably up to date.
|
|
|
+ - Try to keep your copy of Dear ImGui reasonably up to date!
|
|
|
|
|
|
|
|
|
GETTING STARTED WITH INTEGRATING DEAR IMGUI IN YOUR CODE/ENGINE
|
|
|
---------------------------------------------------------------
|
|
|
+ - See https://github.com/ocornut/imgui/wiki/Getting-Started.
|
|
|
- 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 backends files available in the backends/ folder.
|
|
|
- Add the Dear ImGui source files + selected backend source files to your projects or using your preferred build system.
|
|
|
@@ -806,11 +832,12 @@ CODE
|
|
|
|
|
|
Q: Where is the documentation?
|
|
|
A: This library is poorly documented at the moment and expects the user to be acquainted with C/C++.
|
|
|
- - Run the examples/ and explore them.
|
|
|
+ - Run the examples/ applications and explore them.
|
|
|
+ - Read Getting Started (https://github.com/ocornut/imgui/wiki/Getting-Started) guide.
|
|
|
- See demo code in imgui_demo.cpp and particularly the ImGui::ShowDemoWindow() function.
|
|
|
- The demo covers most features of Dear ImGui, so you can read the code and see its output.
|
|
|
- See documentation and comments at the top of imgui.cpp + effectively imgui.h.
|
|
|
- - Dozens of standalone example applications using e.g. OpenGL/DirectX are provided in the
|
|
|
+ - 20+ standalone example applications using e.g. OpenGL/DirectX are provided in the
|
|
|
examples/ folder to explain how to integrate Dear ImGui with your own engine/application.
|
|
|
- The Wiki (https://github.com/ocornut/imgui/wiki) has many resources and links.
|
|
|
- The Glossary (https://github.com/ocornut/imgui/wiki/Glossary) page also may be useful.
|
|
|
@@ -826,14 +853,14 @@ CODE
|
|
|
================
|
|
|
|
|
|
Q: How to get started?
|
|
|
- A: Read 'PROGRAMMER GUIDE' above. Read examples/README.txt.
|
|
|
+ A: Read https://github.com/ocornut/imgui/wiki/Getting-Started. Read 'PROGRAMMER GUIDE' above. Read examples/README.txt.
|
|
|
|
|
|
Q: How can I tell whether to dispatch mouse/keyboard to Dear ImGui or my application?
|
|
|
A: You should read the 'io.WantCaptureMouse', 'io.WantCaptureKeyboard' and 'io.WantTextInput' flags!
|
|
|
>> See https://www.dearimgui.com/faq for a 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. How can I enable keyboard or gamepad controls?
|
|
|
+ Q: How can I use this on a machine without mouse, keyboard or screen? (input share, remote display)
|
|
|
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...
|
|
|
@@ -848,7 +875,7 @@ CODE
|
|
|
- How can I have multiple widgets with the same label?
|
|
|
- How can I have multiple windows with the same label?
|
|
|
Q: How can I display an image? What is ImTextureID, how does it work?
|
|
|
- Q: How can I use my own math types instead of ImVec2/ImVec4?
|
|
|
+ Q: How can I use my own math types instead of ImVec2?
|
|
|
Q: How can I interact with standard C++ types (such as std::string and std::vector)?
|
|
|
Q: How can I display custom shapes? (using low-level ImDrawList API)
|
|
|
>> See https://www.dearimgui.com/faq
|
|
|
@@ -878,10 +905,10 @@ CODE
|
|
|
Q: How can I help?
|
|
|
A: - Businesses: please reach out to "contact AT dearimgui.com" if you work in a place using Dear ImGui!
|
|
|
We can discuss ways for your company to fund development via invoiced technical support, maintenance or sponsoring contacts.
|
|
|
- This is among the most useful thing you can do for Dear ImGui. With increased funding, we can hire more people working on this project.
|
|
|
- - Individuals: you can support continued development via PayPal donations. See README.
|
|
|
- - If you are experienced with Dear ImGui and C++, look at the GitHub issues, look at the Wiki, read docs/TODO.txt
|
|
|
- and see how you want to help and can help!
|
|
|
+ This is among the most useful thing you can do for Dear ImGui. With increased funding, we sustain and grow work on this project.
|
|
|
+ Also see https://github.com/ocornut/imgui/wiki/Sponsors
|
|
|
+ - Businesses: you can also purchase licenses for the Dear ImGui Automation/Test Engine.
|
|
|
+ - If you are experienced with Dear ImGui and C++, look at the GitHub issues, look at the Wiki, and see how you want to help and can help!
|
|
|
- Disclose your usage of Dear ImGui via a dev blog post, a tweet, a screenshot, a mention somewhere etc.
|
|
|
You may post screenshot or links in the gallery threads. Visuals are ideal as they inspire other programmers.
|
|
|
But even without visuals, disclosing your use of dear imgui helps the library grow credibility, and help other teams and programmers with taking decisions.
|
ocornut