mirror of
https://github.com/Drezil/imgui.git
synced 2024-11-22 11:57:00 +00:00
Comments, documentation
This commit is contained in:
parent
a1b6766d43
commit
cdf51cad2d
@ -32,20 +32,14 @@ You can find binaries of some of those example applications at:
|
||||
MISC COMMENTS AND SUGGESTIONS
|
||||
---------------------------------------
|
||||
|
||||
- Newcomers, read 'PROGRAMMER GUIDE' in imgui.cpp for notes on how to setup ImGui in your codebase.
|
||||
|
||||
- Please read the comments and instruction at the top of each file.
|
||||
|
||||
- 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.
|
||||
|
||||
- If you are using of the backend provided here, so you can copy 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
|
||||
catch up with what changed.
|
||||
|
||||
- To LEARN how to setup imgui, you may refer to 'example_glfw_opengl2/' because is the simplest one to read.
|
||||
However, do NOT USE the OpenGL2 renderer if your code is using any modern GL3+ calls.
|
||||
Mixing old fixed-pipeline OpenGL2 and modern OpenGL3+ is going to make everything more complicated.
|
||||
Read comments below for details. If you are not sure, in doubt, use the OpenGL3 renderer.
|
||||
|
||||
- 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).
|
||||
@ -54,8 +48,8 @@ You can find binaries of some of those example applications at:
|
||||
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 are not sure who to blame if you feeling that dragging something is laggy, try to build an
|
||||
application drawing a shape directly under the mouse cursor.
|
||||
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.
|
||||
|
||||
|
||||
---------------------------------------
|
||||
@ -82,8 +76,8 @@ Most the example bindings are split in 2 parts:
|
||||
imgui_impl_xxxx files to fit under your coding style, consider that it is not necessary!
|
||||
In fact, if you are new to Dear ImGui, rewriting them will almost always be harder.
|
||||
|
||||
Example: your engine is built over Windows + DirectX11 but you have your own high-level rendering system
|
||||
layered over DirectX11.
|
||||
Example: your engine is built over Windows + DirectX11 but you have your own high-level rendering
|
||||
system layered over DirectX11.
|
||||
Suggestion: step 1: try using imgui_impl_win32.cpp + imgui_impl_dx11.cpp first.
|
||||
Once this work, _if_ you want you can replace the imgui_impl_dx11.cpp code with a custom renderer
|
||||
using your own functions, etc.
|
||||
@ -102,8 +96,8 @@ Most the example bindings are split in 2 parts:
|
||||
integration. It is also much more complicated and require more work to integrate correctly.
|
||||
If you are new to imgui and you are trying to integrate it into your application, first try to ignore
|
||||
everything related to Viewport and Platform Windows. You'll be able to come back to it later!
|
||||
Note that if you decide to use unmodified imgui_impl_xxxx.cpp files, you will automatically benefit from
|
||||
improvements and fixes related to viewports and platform windows without extra work on your side.
|
||||
Note that if you decide to use unmodified imgui_impl_xxxx.cpp files, you will automatically benefit
|
||||
from improvements and fixes related to viewports and platform windows without extra work on your side.
|
||||
See 'ImGuiPlatformIO' for details.
|
||||
|
||||
List of Platforms Bindings in this repository:
|
||||
@ -119,7 +113,7 @@ List of Renderer Bindings in this repository:
|
||||
imgui_impl_dx10.cpp ; DirectX10
|
||||
imgui_impl_dx11.cpp ; DirectX11
|
||||
imgui_impl_dx12.cpp ; DirectX12
|
||||
imgui_impl_opengl2.cpp ; OpenGL2 (legacy, fixed pipeline)
|
||||
imgui_impl_opengl2.cpp ; OpenGL2 (legacy, fixed pipeline <- don't use with modern OpenGL context)
|
||||
imgui_impl_opengl3.cpp ; OpenGL3 (modern programmable pipeline)
|
||||
imgui_impl_vulkan.cpp ; Vulkan
|
||||
|
||||
@ -224,6 +218,10 @@ example_allegro5/
|
||||
Allegro 5 example.
|
||||
= main.cpp + imgui_impl_allegro5.cpp
|
||||
|
||||
example_freeglut_opengl2/
|
||||
FreeGLUT + OpenGL2.
|
||||
= main.cpp + imgui_impl_freeglut.cpp + imgui_impl_opengl2.cpp
|
||||
|
||||
example_marmalade/
|
||||
Marmalade example using IwGx.
|
||||
= main.cpp + imgui_impl_marmalade.cpp
|
||||
|
@ -7,7 +7,8 @@
|
||||
#include "imgui_impl_glfw.h"
|
||||
#include "imgui_impl_opengl3.h"
|
||||
#include <stdio.h>
|
||||
#include <GL/gl3w.h> // This example is using gl3w to access OpenGL functions (because it is small). You may use glew/glad/glLoadGen/etc. whatever already works for you.
|
||||
#include <GL/gl3w.h> // This example is using gl3w to access OpenGL functions. You may freely use any other OpenGL loader such as: glew, glad, glLoadGen, etc.
|
||||
//#include <glew.h>
|
||||
#include <GLFW/glfw3.h>
|
||||
|
||||
static void glfw_error_callback(int error, const char* description)
|
||||
|
@ -7,7 +7,8 @@
|
||||
#include "imgui_impl_sdl.h"
|
||||
#include "imgui_impl_opengl3.h"
|
||||
#include <stdio.h>
|
||||
#include <GL/gl3w.h> // This example is using gl3w to access OpenGL functions (because it is small). You may use glew/glad/glLoadGen/etc. whatever already works for you.
|
||||
#include <GL/gl3w.h> // This example is using gl3w to access OpenGL functions. You may freely use any other OpenGL loader such as: glew, glad, glLoadGen, etc.
|
||||
//#include <glew.h>
|
||||
#include <SDL.h>
|
||||
|
||||
int main(int, char**)
|
||||
|
@ -27,7 +27,8 @@
|
||||
|
||||
#include "imgui.h"
|
||||
#include "imgui_impl_opengl3.h"
|
||||
#include <GL/gl3w.h> // This example is using gl3w to access OpenGL functions (because it is small). You may use glew/glad/glLoadGen/etc. whatever already works for you.
|
||||
#include <GL/gl3w.h> // This example is using gl3w to access OpenGL functions. You may freely use any other OpenGL loader such as: glew, glad, glLoadGen, etc.
|
||||
//#include <glew.h>
|
||||
|
||||
// OpenGL Data
|
||||
static char g_GlslVersion[32] = "#version 150";
|
||||
|
76
imgui.cpp
76
imgui.cpp
@ -109,43 +109,33 @@
|
||||
GETTING STARTED WITH INTEGRATING DEAR IMGUI IN YOUR CODE/ENGINE
|
||||
|
||||
- Run and study the examples and demo to get acquainted with the library.
|
||||
- Add the Dear ImGui source files to your projects, using your preferred build system.
|
||||
- Add the Dear ImGui source files to your projects or 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.
|
||||
- You may be able to grab and copy a ready made imgui_impl_*** file from the examples/ folder.
|
||||
- When using Dear ImGui, your programming IDE is your friend: follow the declaration of variables, functions and types to find comments about them.
|
||||
- Dear ImGui never touches or knows about your GPU state. The only function that knows about GPU is the draw function 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. All rendering informatioe are stored into command-lists that you will retrieve after calling ImGui::Render().
|
||||
- Refer to the bindings and demo applications in the examples/ folder for instruction on how to setup your code.
|
||||
|
||||
- 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 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.
|
||||
(Even if you don't render, call Render() and ignore the callback, or call EndFrame() instead. Otherwise some features will break)
|
||||
- All rendering information are stored into command-lists until ImGui::Render() is called.
|
||||
- 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:
|
||||
THIS IS HOW A SIMPLE APPLICATION MAY LOOK LIKE
|
||||
|
||||
// Application init
|
||||
// Create a context
|
||||
ImGui::CreateContext();
|
||||
ImGuiIO& io = ImGui::GetIO();
|
||||
io.DisplaySize.x = 1920.0f;
|
||||
io.DisplaySize.y = 1280.0f;
|
||||
// TODO: Fill others settings of the io structure later.
|
||||
// TODO: Fill optional settings of the io structure later.
|
||||
// TODO: Load fonts if you don't want to use the default font.
|
||||
|
||||
// Load texture atlas (there is a default font so you don't need to care about choosing a font yet)
|
||||
unsigned char* pixels;
|
||||
// Build and load the texture atlas into a texture
|
||||
unsigned char* pixels = NULL;
|
||||
int width, height;
|
||||
io.Fonts->GetTexDataAsRGBA32(&pixels, &width, &height);
|
||||
// TODO: At this points you've got the texture data and you need to upload that your your graphic system:
|
||||
MyTexture* texture = MyEngine::CreateTextureFromMemoryPixels(pixels, width, height, TEXTURE_TYPE_RGBA)
|
||||
// TODO: Store your texture pointer/identifier (whatever your engine uses) in 'io.Fonts->TexID'. This will be passed back to your via the renderer.
|
||||
// At this point you've got the texture data and you need to upload that your your graphic system:
|
||||
MyTexture* texture = MyEngine::CreateTextureFromMemoryPixels(pixels, width, height, TEXTURE_TYPE_RGBA32)
|
||||
// Store your texture pointer/identifier (in whatever formatyour engine uses) in 'io.Fonts->TexID'.
|
||||
// This will be passed back to your via the renderer. Read FAQ for details about ImTextureID.
|
||||
io.Fonts->TexID = (void*)texture;
|
||||
|
||||
// Application main loop
|
||||
@ -154,18 +144,24 @@
|
||||
// Setup low-level inputs (e.g. on Win32, GetKeyboardState(), or write to those fields from your Windows message loop handlers, etc.)
|
||||
ImGuiIO& io = ImGui::GetIO();
|
||||
io.DeltaTime = 1.0f/60.0f;
|
||||
io.MousePos = mouse_pos;
|
||||
io.MouseDown[0] = mouse_button_0;
|
||||
io.MouseDown[1] = mouse_button_1;
|
||||
io.DisplaySize.x = 1920.0f;
|
||||
io.DisplaySize.y = 1280.0f;
|
||||
io.MousePos = my_mouse_pos;
|
||||
io.MouseDown[0] = my_mouse_buttons[0];
|
||||
io.MouseDown[1] = my_mouse_buttons[1];
|
||||
|
||||
// Call NewFrame(), after this point you can use ImGui::* functions anytime
|
||||
// (So you want to try calling Newframe() as early as you can in your mainloop to be able to use imgui everywhere)
|
||||
ImGui::NewFrame();
|
||||
|
||||
// Most of your application code here
|
||||
ImGui::Text("Hello, world!");
|
||||
MyGameUpdate(); // may use any ImGui functions, e.g. ImGui::Begin("My window"); ImGui::Text("Hello, world!"); ImGui::End();
|
||||
MyGameRender(); // may use any ImGui functions as well!
|
||||
|
||||
// Render & swap video buffers
|
||||
// Render imgui, swap buffers
|
||||
// (You want to try calling EndFrame/Render as late as you can, to be able to use imgui in your own game rendering code)
|
||||
ImGui::EndFrame();
|
||||
ImGui::Render();
|
||||
MyImGuiRenderFunction(ImGui::GetDrawData());
|
||||
SwapBuffers();
|
||||
@ -174,13 +170,13 @@
|
||||
// Shutdown
|
||||
ImGui::DestroyContext();
|
||||
|
||||
THIS HOW A SIMPLE RENDERING FUNCTION MAY LOOK LIKE
|
||||
|
||||
- A minimal render function skeleton may be:
|
||||
|
||||
void void MyRenderFunction(ImDrawData* draw_data)
|
||||
void void MyImGuiRenderFunction(ImDrawData* draw_data)
|
||||
{
|
||||
// TODO: Setup render state: alpha-blending enabled, no face culling, no depth testing, scissor enabled
|
||||
// TODO: Setup viewport, orthographic projection matrix
|
||||
// TODO: Setup viewport using draw_data->DisplaySize
|
||||
// TODO: Setup orthographic projection matrix cover draw_data->DisplayPos to draw_data->DisplayPos + draw_data->DisplaySize
|
||||
// TODO: Setup shader: vertex { float2 pos, float2 uv, u32 color }, fragment shader sample color from 1 texture, multiply by vertex color.
|
||||
for (int n = 0; n < draw_data->CmdListsCount; n++)
|
||||
{
|
||||
@ -199,10 +195,16 @@
|
||||
// The vast majority of draw calls with use the imgui texture atlas, which value you have set yourself during initialization.
|
||||
MyEngineBindTexture(pcmd->TextureId);
|
||||
|
||||
// We are using scissoring to clip some objects. All low-level graphics API supports it.
|
||||
// If your engine doesn't support scissoring yet, you may ignore this at first. You will get some small glitches
|
||||
// (some elements visible outside their bounds) but you can fix that once everywhere else works!
|
||||
MyEngineScissor((int)pcmd->ClipRect.x, (int)pcmd->ClipRect.y, (int)(pcmd->ClipRect.z - pcmd->ClipRect.x), (int)(pcmd->ClipRect.w - pcmd->ClipRect.y));
|
||||
// We are using scissoring to clip some objects. All low-level graphics API should supports it.
|
||||
// - If your engine doesn't support scissoring yet, you may ignore this at first. You will get some small glitches
|
||||
// (some elements visible outside their bounds) but you can fix that once everywhere else works!
|
||||
// - Clipping coordinates are provided in imgui coordinates space (from draw_data->DisplayPos to draw_data->DisplayPos + draw_data->DisplaySize)
|
||||
// In a single viewport application, draw_data->DisplayPos will always be (0,0) and draw_data->DisplaySize will always be == io.DisplaySize.
|
||||
// However, in the interest of supporting multi-viewport applications in the future, always subtract draw_data->DisplayPos from
|
||||
// clipping bounds to convert them to your viewport space.
|
||||
// - Note that pcmd->ClipRect contains Min+Max bounds. Some graphics API may use Min+Max, other may use Min+Size (size being Max-Min)
|
||||
ImVec2 pos = draw_data->DisplayPos;
|
||||
MyEngineScissor((int)(pcmd->ClipRect.x - pos.x), (int)(pcmd->ClipRect.y - pos.y), (int)(pcmd->ClipRect.z - pos.x), (int)(pcmd->ClipRect.w - pos.y));
|
||||
|
||||
// Render 'pcmd->ElemCount/3' indexed triangles.
|
||||
// By default the indices ImDrawIdx are 16-bits, you can change them to 32-bits if your engine doesn't support 16-bits indices.
|
||||
|
Loading…
Reference in New Issue
Block a user