mirror of
https://github.com/xemu-project/imgui.git
synced 2024-11-23 18:29:51 +00:00
Tweaked FAQ.
This commit is contained in:
omar
parent
ac5b7a1bdf
commit
5097368bd5
@ -153,10 +153,9 @@ I occasionally tag [Releases](https://github.com/ocornut/imgui/releases) but it
|
||||
|
||||
The library started its life and is best known as "ImGui" only due to the fact that I didn't give it a proper name when I released it. However, the term IMGUI (immediate-mode graphical user interface) was coined before and is being used in variety of other situations. It seemed confusing and unfair to hog the name. To reduce the ambiguity without affecting existing codebases, I have decided on an alternate, longer name "dear imgui" that people can use to refer to this specific library in ambiguous situations.
|
||||
|
||||
<b>What is ImTextureID and how do I display an image?</b>
|
||||
<br><b>I integrated Dear ImGui in my engine and the text or lines are blurry..</b>
|
||||
<br><b>I integrated Dear ImGui in my engine and some elements are disappearing when I move windows around..</b>
|
||||
<br><b>How can I have multiple widgets with the same label? Can I have widget without a label? (Yes). A primer on labels/IDs.</b>
|
||||
<b>How can I help</b>
|
||||
<br><b>How can I display an image? What is ImTextureID, how does it works?</b>
|
||||
<br><b>How can I have multiple widgets with the same label? Can I have widget without a label? (Yes). A primer on labels and the ID stack.</b>
|
||||
<br><b>How can I tell when Dear ImGui wants my mouse/keyboard inputs VS when I can pass them to my application?</b>
|
||||
<br><b>How can I load a different font than the default?</b>
|
||||
<br><b>How can I easily use icons in my application?</b>
|
||||
@ -164,6 +163,8 @@ The library started its life and is best known as "ImGui" only due to the fact t
|
||||
<br><b>How can I display and input non-latin characters such as Chinese, Japanese, Korean, Cyrillic?</b>
|
||||
<br><b>How can I preserve my Dear ImGui context across reloading a DLL? (loss of the global/static variables)</b>
|
||||
<br><b>How can I use the drawing facilities without an Dear ImGui window? (using ImDrawList API)</b>
|
||||
<br><b>I integrated Dear ImGui in my engine and the text or lines are blurry..</b>
|
||||
<br><b>I integrated Dear ImGui in my engine and some elements are disappearing when I move windows around..</b>
|
||||
|
||||
See the FAQ in imgui.cpp for answers.
|
||||
|
||||
|
||||
78
imgui.cpp
78
imgui.cpp
@ -23,10 +23,8 @@
|
||||
- ISSUES & TODO LIST
|
||||
- FREQUENTLY ASKED QUESTIONS (FAQ), TIPS
|
||||
- How can I help?
|
||||
- What is ImTextureID and how do I display an image?
|
||||
- I integrated Dear ImGui in my engine and the text or lines are blurry..
|
||||
- I integrated Dear ImGui in my engine and some elements are clipping or disappearing when I move windows around..
|
||||
- How can I have multiple widgets with the same label? Can I have widget without a label? (Yes). A primer on labels/IDs.
|
||||
- How can I dipslay an image? What is ImTextureID, how does it works?
|
||||
- How can I have multiple widgets with the same label? Can I have widget without a label? (Yes). A primer on labels and the ID stack.
|
||||
- How can I tell when Dear ImGui wants my mouse/keyboard inputs VS when I can pass them to my application?
|
||||
- How can I load a different font than the default?
|
||||
- How can I easily use icons in my application?
|
||||
@ -34,6 +32,8 @@
|
||||
- How can I display and input non-latin characters such as Chinese, Japanese, Korean, Cyrillic?
|
||||
- How can I preserve my Dear ImGui context across reloading a DLL? (loss of the global/static variables)
|
||||
- How can I use the drawing facilities without an ImGui window? (using ImDrawList API)
|
||||
- I integrated Dear ImGui in my engine and the text or lines are blurry..
|
||||
- I integrated Dear ImGui in my engine and some elements are clipping or disappearing when I move windows around..
|
||||
- ISSUES & TODO-LIST
|
||||
- CODE
|
||||
|
||||
@ -374,10 +374,14 @@
|
||||
======================================
|
||||
|
||||
Q: How can I help?
|
||||
A: - If you are experienced enough with Dear ImGui and with C/C++, look at the todo list and see how you want/can help!
|
||||
- Become a Patron/donate! Convince your company to become a Patron or provide serious funding for development time! See http://www.patreon.com/imgui
|
||||
A: - If you are experienced with Dear ImGui and C++, look at the github issues, or TODO.txt and see how you want/can help!
|
||||
- Convince your company to fund development time! Individual users: you can also become a Patron (patreon.com/imgui) or donate on PayPal! See README.
|
||||
- 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 (github.com/ocornut/imgui/issues/1269). Visuals are ideal as they inspire other programmers.
|
||||
But even without visuals, disclosing your use of dear imgui help the library grow credibility, and help other teams and programmers with taking decisions.
|
||||
- If you have issues or if you need to hack into the library, even if you don't expect any support it is useful that you share your issues (on github or privately).
|
||||
|
||||
Q: What is ImTextureID and how do I display an image?
|
||||
Q: How can I display an image? What is ImTextureID, how does it works?
|
||||
A: ImTextureID is a void* used to pass renderer-agnostic texture references around until it hits your render function.
|
||||
Dear ImGui knows nothing about what those bits represent, it just passes them around. It is up to you to decide what you want the void* to carry!
|
||||
It could be an identifier to your OpenGL texture (cast GLuint to void*), a pointer to your custom engine material (cast MyMaterial* to void*), etc.
|
||||
@ -386,26 +390,19 @@
|
||||
(c++ tip: OpenGL uses integers to identify textures. You can safely store an integer into a void*, just cast it to void*, don't take it's address!)
|
||||
To display a custom image/texture within an ImGui window, you may use ImGui::Image(), ImGui::ImageButton(), ImDrawList::AddImage() functions.
|
||||
Dear ImGui will generate the geometry and draw calls using the ImTextureID that you passed and which your renderer can use.
|
||||
You may call ImGui::ShowMetricsWindow() to explore active draw lists and visualize/understand how the draw data is generated.
|
||||
It is your responsibility to get textures uploaded to your GPU.
|
||||
|
||||
Q: I integrated Dear ImGui in my engine and the text or lines are blurry..
|
||||
A: 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 some elements are clipping or disappearing when I move windows around..
|
||||
A: You are probably mishandling the clipping rectangles in your render function.
|
||||
Rectangles provided by ImGui are defined as (x1=left,y1=top,x2=right,y2=bottom) and NOT as (x1,y1,width,height).
|
||||
|
||||
Q: Can I have multiple widgets with the same label? Can I have widget without a label?
|
||||
A: Yes. A primer on the use of labels/IDs in Dear ImGui..
|
||||
A: Yes. A primer on labels and the ID stack...
|
||||
|
||||
- Elements that are not clickable, such as Text() items don't need an ID.
|
||||
- Elements that are typically not clickable, such as Text() items don't need an ID.
|
||||
|
||||
- Interactive widgets require state to be carried over multiple frames (most typically Dear ImGui often needs to remember what is
|
||||
the "active" widget). to do so they need a unique ID. unique ID are typically derived from a string label, an integer index or a pointer.
|
||||
|
||||
Button("OK"); // Label = "OK", ID = hash of "OK"
|
||||
Button("Cancel"); // Label = "Cancel", ID = hash of "Cancel"
|
||||
Button("OK"); // Label = "OK", ID = hash of "OK"
|
||||
Button("Cancel"); // Label = "Cancel", ID = hash of "Cancel"
|
||||
|
||||
- ID are uniquely scoped within windows, tree nodes, etc. so no conflict can happen if you have two buttons called "OK"
|
||||
in two different windows or in two different locations of a tree.
|
||||
@ -413,34 +410,35 @@
|
||||
- If you have a same ID twice in the same location, you'll have a conflict:
|
||||
|
||||
Button("OK");
|
||||
Button("OK"); // ID collision! Both buttons will be treated as the same.
|
||||
Button("OK"); // ID collision! Both buttons will be treated as the same.
|
||||
|
||||
Fear not! this is easy to solve and there are many ways to solve it!
|
||||
|
||||
- When passing a label you can optionally specify extra unique ID information within string itself.
|
||||
This helps solving the simpler collision cases. Use "##" to pass a complement to the ID that won't be visible to the end-user:
|
||||
- When passing a label you can optionally specify extra unique ID information within string itself.
|
||||
Use "##" to pass a complement to the ID that won't be visible to the end-user.
|
||||
This helps solving the simple collision cases when you know which items are going to be created.
|
||||
|
||||
Button("Play"); // Label = "Play", ID = hash of "Play"
|
||||
Button("Play##foo1"); // Label = "Play", ID = hash of "Play##foo1" (different from above)
|
||||
Button("Play##foo2"); // Label = "Play", ID = hash of "Play##foo2" (different from above)
|
||||
Button("Play"); // Label = "Play", ID = hash of "Play"
|
||||
Button("Play##foo1"); // Label = "Play", ID = hash of "Play##foo1" (different from above)
|
||||
Button("Play##foo2"); // Label = "Play", ID = hash of "Play##foo2" (different from above)
|
||||
|
||||
- If you want to completely hide the label, but still need an ID:
|
||||
|
||||
Checkbox("##On", &b); // Label = "", ID = hash of "##On" (no label!)
|
||||
Checkbox("##On", &b); // Label = "", ID = hash of "##On" (no label!)
|
||||
|
||||
- Occasionally/rarely you might want change a label while preserving a constant ID. This allows you to animate labels.
|
||||
For example you may want to include varying information in a window title bar (and windows are uniquely identified by their ID.. obviously)
|
||||
For example you may want to include varying information in a window title bar, but windows are uniquely identified by their ID..
|
||||
Use "###" to pass a label that isn't part of ID:
|
||||
|
||||
Button("Hello###ID"; // Label = "Hello", ID = hash of "ID"
|
||||
Button("World###ID"; // Label = "World", ID = hash of "ID" (same as above)
|
||||
|
||||
sprintf(buf, "My game (%f FPS)###MyGame");
|
||||
sprintf(buf, "My game (%f FPS)###MyGame", fps);
|
||||
Begin(buf); // Variable label, ID = hash of "MyGame"
|
||||
|
||||
- Use PushID() / PopID() to create scopes and avoid ID conflicts within the same Window.
|
||||
This is the most convenient way of distinguishing ID if you are iterating and creating many UI elements.
|
||||
You can push a pointer, a string or an integer value. Remember that ID are formed from the concatenation of everything in the ID stack!
|
||||
You can push a pointer, a string or an integer value. Remember that ID are formed from the concatenation of _everything_ in the ID stack!
|
||||
|
||||
for (int i = 0; i < 100; i++)
|
||||
{
|
||||
@ -570,16 +568,25 @@
|
||||
so you don't rely on the default globals.
|
||||
|
||||
Q: How can I use the drawing facilities without an ImGui window? (using ImDrawList API)
|
||||
A: The easiest way is to create a dummy window. Call Begin() with NoTitleBar|NoResize|NoMove|NoScrollbar|NoSavedSettings|NoInputs flag,
|
||||
zero background alpha, then retrieve the ImDrawList* via GetWindowDrawList() and draw to it in any way you like.
|
||||
You can also perfectly create a standalone ImDrawList instance _but_ you need ImGui to be initialized because ImDrawList pulls from ImGui
|
||||
data to retrieve the coordinates of the white pixel.
|
||||
A: - You can create a dummy window. Call Begin() with NoTitleBar|NoResize|NoMove|NoScrollbar|NoSavedSettings|NoInputs flag,
|
||||
push a ImGuiCol_WindowBg with zero alpha, then retrieve the ImDrawList* via GetWindowDrawList() and draw to it in any way you like.
|
||||
- You can call ImGui::GetOverlayDrawList() and use this draw list to display contents over every other imgui windows.
|
||||
- You can create your own ImDrawList instance. You'll need to initialize them ImGui::GetDrawListSharedData(), or create your own ImDrawListSharedData.
|
||||
|
||||
Q: I integrated Dear ImGui in my engine and the text or lines are blurry..
|
||||
A: 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 some elements are clipping or disappearing when I move windows around..
|
||||
A: You are probably mishandling the clipping rectangles in your render function.
|
||||
Rectangles provided by ImGui are defined as (x1=left,y1=top,x2=right,y2=bottom) and NOT as (x1,y1,width,height).
|
||||
|
||||
|
||||
- tip: you can call Begin() multiple times with the same name during the same frame, it will keep appending to the same window.
|
||||
this is also useful to set yourself in the context of another window (to get/set other settings)
|
||||
this is also useful to set yourself in the context of another window (to get/set other settings)
|
||||
- tip: you can create widgets without a Begin()/End() block, they will go in an implicit window called "Debug".
|
||||
- tip: the ImGuiOnceUponAFrame helper will allow run the block of code only once a frame. You can use it to quickly add custom UI in the middle
|
||||
of a deep nested inner loop in your code.
|
||||
of a deep nested inner loop in your code.
|
||||
- tip: you can call Render() multiple times (e.g for VR renders).
|
||||
- tip: call and read the ShowDemoWindow() code in imgui_demo.cpp for more example of how to use ImGui!
|
||||
|
||||
@ -3914,6 +3921,7 @@ bool ImGui::BeginPopupModal(const char* name, bool* p_open, ImGuiWindowFlags fla
|
||||
}
|
||||
|
||||
// Center modal windows by default
|
||||
// FIXME: Should test for (PosCond & window->SetWindowPosAllowFlags) with the upcoming window.
|
||||
if (g.NextWindowData.PosCond == 0)
|
||||
SetNextWindowPos(g.IO.DisplaySize * 0.5f, ImGuiCond_Appearing, ImVec2(0.5f, 0.5f));
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user