mirror of
https://github.com/Drezil/imgui.git
synced 2024-11-15 01:17:00 +00:00
More consistently uses "Dear ImGui"
This commit is contained in:
omar
parent
83645aa593
commit
052999a6ab
50
imgui.cpp
50
imgui.cpp
@ -2,7 +2,7 @@
|
||||
// (main code and documentation)
|
||||
|
||||
// See ImGui::ShowTestWindow() in imgui_demo.cpp for demo code.
|
||||
// Newcomers, read 'Programmer guide' below for notes on how to setup ImGui in your codebase.
|
||||
// Newcomers, read 'Programmer guide' below for notes on how to setup Dear ImGui in your codebase.
|
||||
// Get latest version at https://github.com/ocornut/imgui
|
||||
// Releases change-log at https://github.com/ocornut/imgui/releases
|
||||
// Gallery (please post your screenshots/video there!): https://github.com/ocornut/imgui/issues/1269
|
||||
@ -17,22 +17,22 @@
|
||||
- END-USER GUIDE
|
||||
- PROGRAMMER GUIDE (read me!)
|
||||
- Read first
|
||||
- How to update to a newer version of ImGui
|
||||
- Getting started with integrating ImGui in your code/engine
|
||||
- How to update to a newer version of Dear ImGui
|
||||
- Getting started with integrating Dear ImGui in your code/engine
|
||||
- API BREAKING CHANGES (read me when you update!)
|
||||
- ISSUES & TODO LIST
|
||||
- FREQUENTLY ASKED QUESTIONS (FAQ), TIPS
|
||||
- How can I help?
|
||||
- What is ImTextureID and how do I display an image?
|
||||
- I integrated ImGui in my engine and the text or lines are blurry..
|
||||
- I integrated ImGui in my engine and some elements are clipping or disappearing when I move windows around..
|
||||
- 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 tell when ImGui wants my mouse/keyboard inputs VS when I can pass them to my application?
|
||||
- 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?
|
||||
- How can I load multiple fonts?
|
||||
- How can I display and input non-latin characters such as Chinese, Japanese, Korean, Cyrillic?
|
||||
- How can I preserve my ImGui context across reloading a DLL? (loss of the global/static variables)
|
||||
- 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)
|
||||
- ISSUES & TODO-LIST
|
||||
- CODE
|
||||
@ -89,7 +89,7 @@
|
||||
- Call and read ImGui::ShowTestWindow() for demo code demonstrating most features.
|
||||
- You can learn about immediate-mode gui principles at http://www.johno.se/book/imgui.html or watch http://mollyrocket.com/861
|
||||
|
||||
HOW TO UPDATE TO A NEWER VERSION OF IMGUI
|
||||
HOW TO UPDATE TO A NEWER VERSION OF DEAR IMGUI
|
||||
|
||||
- Overwrite all the sources files except for imconfig.h (if you have made modification to your copy of imconfig.h)
|
||||
- Read the "API BREAKING CHANGES" section (below). This is where we list occasional API breaking changes.
|
||||
@ -98,26 +98,26 @@
|
||||
Please report any issue to the GitHub page!
|
||||
- Try to keep your copy of dear imgui reasonably up to date.
|
||||
|
||||
GETTING STARTED WITH INTEGRATING IMGUI IN YOUR CODE/ENGINE
|
||||
GETTING STARTED WITH INTEGRATING DEAR IMGUI IN YOUR CODE/ENGINE
|
||||
|
||||
- Add the ImGui source files to your projects, using your preferred build system. It is recommended you build the .cpp files as part of your project and not as a library.
|
||||
- Add the Dear ImGui source files to your projects, using your preferred build system. It is recommended you build the .cpp files as part of your project and not as a library.
|
||||
- You can later customize the imconfig.h file to tweak some compilation time behavior, such as integrating imgui types with your own maths types.
|
||||
- See examples/ folder for standalone sample applications. To understand the integration process, you can read examples/opengl2_example/ because it is short,
|
||||
then switch to the one more appropriate to your use case.
|
||||
- You may be able to grab and copy a ready made imgui_impl_*** file from the examples/.
|
||||
- When using ImGui, your programming IDE if your friend: follow the declaration of variables, functions and types to find comments about them.
|
||||
- When using Dear ImGui, your programming IDE if your friend: follow the declaration of variables, functions and types to find comments about them.
|
||||
|
||||
- Init: retrieve the ImGuiIO structure with ImGui::GetIO() and fill the fields marked 'Settings': at minimum you need to set io.DisplaySize (application resolution).
|
||||
Later on you will fill your keyboard mapping, clipboard handlers, and other advanced features but for a basic integration you don't need to worry about it all.
|
||||
- Init: call io.Fonts->GetTexDataAsRGBA32(...), it will build the font atlas texture, then load the texture pixels into graphics memory.
|
||||
- Every frame:
|
||||
- In your main loop as early a possible, fill the IO fields marked 'Input' (e.g. mouse position, buttons, keyboard info, etc.)
|
||||
- Call ImGui::NewFrame() to begin the imgui frame
|
||||
- Call ImGui::NewFrame() to begin the frame
|
||||
- You can use any ImGui function you want between NewFrame() and Render()
|
||||
- Call ImGui::Render() as late as you can to end the frame and finalize render data. it will call your io.RenderDrawListFn handler.
|
||||
(if you don't need to render, you still need to call Render() and ignore the callback, or call EndFrame() instead. if you call neither some aspects of windows focusing/moving will appear broken.)
|
||||
- All rendering information are stored into command-lists until ImGui::Render() is called.
|
||||
- ImGui never touches or knows about your GPU state. the only function that knows about GPU is the RenderDrawListFn handler that you provide.
|
||||
- Dear ImGui never touches or knows about your GPU state. the only function that knows about GPU is the RenderDrawListFn handler that you provide.
|
||||
- Effectively it means you can create widgets at any time in your code, regardless of considerations of being in "update" vs "render" phases of your own application.
|
||||
- Refer to the examples applications in the examples/ folder for instruction on how to setup your code.
|
||||
- A minimal application skeleton may be:
|
||||
@ -338,33 +338,33 @@
|
||||
======================================
|
||||
|
||||
Q: How can I help?
|
||||
A: - If you are experienced enough with ImGui and with C/C++, look at the todo list and see how you want/can 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
|
||||
|
||||
Q: What is ImTextureID and how do I display an image?
|
||||
A: ImTextureID is a void* used to pass renderer-agnostic texture references around until it hits your render function.
|
||||
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!
|
||||
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.
|
||||
At the end of the chain, your renderer takes this void* to cast it back into whatever it needs to select a current texture to render.
|
||||
Refer to examples applications, where each renderer (in a imgui_impl_xxxx.cpp file) is treating ImTextureID as a different thing.
|
||||
(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.
|
||||
ImGui will generate the geometry and draw calls using the ImTextureID that you passed and which your renderer can use.
|
||||
Dear ImGui will generate the geometry and draw calls using the ImTextureID that you passed and which your renderer can use.
|
||||
It is your responsibility to get textures uploaded to your GPU.
|
||||
|
||||
Q: I integrated 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..
|
||||
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 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..
|
||||
A: Most likely you are 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 ImGui..
|
||||
A: Yes. A primer on the use of labels/IDs in Dear ImGui..
|
||||
|
||||
- Elements that are not clickable, such as Text() items don't need an ID.
|
||||
|
||||
- Interactive widgets require state to be carried over multiple frames (most typically ImGui often needs to remember what is the "active" widget).
|
||||
- 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"
|
||||
@ -452,15 +452,15 @@
|
||||
e.g. when displaying a single object that may change over time (1-1 relationship), using a static string as ID will preserve your node open/closed state when the targeted object change.
|
||||
e.g. when displaying a list of objects, using indices or pointers as ID will preserve the node open/closed state differently. experiment and see what makes more sense!
|
||||
|
||||
Q: How can I tell when ImGui wants my mouse/keyboard inputs VS when I can pass them to my application?
|
||||
Q: How can I tell when Dear ImGui wants my mouse/keyboard inputs VS when I can pass them to my application?
|
||||
A: You can read the 'io.WantCaptureMouse'/'io.WantCaptureKeyboard'/'ioWantTextInput' flags from the ImGuiIO structure.
|
||||
- When 'io.WantCaptureMouse' or 'io.WantCaptureKeyboard' flags are set you may want to discard/hide the inputs from the rest of your application.
|
||||
- When 'io.WantTextInput' is set to may want to notify your OS to popup an on-screen keyboard, if available (e.g. on a mobile phone, or console without a keyboard).
|
||||
Preferably read the flags after calling ImGui::NewFrame() to avoid them lagging by one frame. But reading those flags before calling NewFrame() is also generally ok,
|
||||
as the bool toggles fairly rarely and you don't generally expect to interact with either ImGui or your application during the same frame when that transition occurs.
|
||||
ImGui is tracking dragging and widget activity that may occur outside the boundary of a window, so 'io.WantCaptureMouse' is more accurate and correct than checking if a window is hovered.
|
||||
as the bool toggles fairly rarely and you don't generally expect to interact with either Dear ImGui or your application during the same frame when that transition occurs.
|
||||
Dear ImGui is tracking dragging and widget activity that may occur outside the boundary of a window, so 'io.WantCaptureMouse' is more accurate and correct than checking if a window is hovered.
|
||||
(Advanced note: text input releases focus on Return 'KeyDown', so the following Return 'KeyUp' event that your application receive will typically have 'io.WantCaptureKeyboard=false'.
|
||||
Depending on your application logic it may or not be inconvenient. You might want to track which key-downs were for ImGui (e.g. with an array of bool) and filter out the corresponding key-ups.)
|
||||
Depending on your application logic it may or not be inconvenient. You might want to track which key-downs were for Dear ImGui (e.g. with an array of bool) and filter out the corresponding key-ups.)
|
||||
|
||||
Q: How can I load a different font than the default? (default is an embedded version of ProggyClean.ttf, rendered at size 13)
|
||||
A: Use the font atlas to load the TTF/OTF file you want:
|
||||
@ -523,7 +523,7 @@
|
||||
Text input: it is up to your application to pass the right character code to io.AddInputCharacter(). The applications in examples/ are doing that.
|
||||
For languages using IME, on Windows you can copy the Hwnd of your application to io.ImeWindowHandle. The default implementation of io.ImeSetInputScreenPosFn() on Windows will set your IME position correctly.
|
||||
|
||||
Q: How can I preserve my ImGui context across reloading a DLL? (loss of the global/static variables)
|
||||
Q: How can I preserve my Dear ImGui context across reloading a DLL? (loss of the global/static variables)
|
||||
A: Create your own context 'ctx = CreateContext()' + 'SetCurrentContext(ctx)' and your own font atlas 'ctx->GetIO().Fonts = new ImFontAtlas()' so you don't rely on the default globals.
|
||||
|
||||
Q: How can I use the drawing facilities without an ImGui window? (using ImDrawList API)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user