mirror of
https://github.com/Drezil/imgui.git
synced 2025-07-07 13:35:49 +02:00
Doc: various tweaks + tweak imconfig comments.
This commit is contained in:
ocornut
73
imgui.cpp
73
imgui.cpp
@ -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.
|
||||
|
||||
Reference in New Issue
Block a user