Examples: Extra clarification for the 100th person who insist on using the OpenGL2 code in spite of existing documentation leaning against it. (#1394)

examples/README.txt

@@ -8,15 +8,16 @@ Third party languages and frameworks bindings: https://github.com/ocornut/imgui/
 
 TL;DR; 
  - Newcomers, read 'PROGRAMMER GUIDE' in imgui.cpp for notes on how to setup ImGui in your codebase.
- - To LEARN how the library is setup, you may refer to 'opengl2_example' because is the simplest one.
-   The other examples requires more boilerplate and are harder to read.
-   However, USE 'opengl3_example' in your application if you are using any modern OpenGL3+ calls.
-   Mixing old fixed pipeline OpenGL2 and programmable pipeline OpenGL3+ isn't well supported by some drivers.
-   If you are not sure, in doubt, use 'opengl3_example'.
  - 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.
- - If you have your own engine, you probably want to start from one of the OpenGL example and adapt it to 
+ - To LEARN how the library is setup, you may refer to 'opengl2_example' because is the simplest one to read.
-   your engine, but you can read the other examples as well.
+   However, do NOT USE the 'opengl2_example' 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 'opengl3_example'.
+ - If you have your own engine, you probably want to read a few of the examples first then adapt it to
+   your engine. Please note that if your engine is based on OpenGL/DirectX you can perfectly use the
+   existing rendering backends, don't feel forced to rewrite them with your own engine API, or you can
+   do that later when you already got things to work.
 
 ImGui is highly portable and only requires a few things to run:
  - Providing mouse/keyboard inputs
@@ -45,12 +46,12 @@ Also note that some setup or GPU drivers may be causing extra lag (possibly by e
 leaving you with no option but sadness/anger (Intel GPU drivers were reported as such).
 
 opengl2_example/
+    *DO NOT USE THIS CODE IF YOUR CODE/ENGINE IS USING MODERN OPENGL*
     GLFW + OpenGL example (old, fixed graphic pipeline).
-    This is only provided as a reference to learn how ImGui integration works, because it is easier to read.
+    This is mostly provided as a reference to learn how ImGui integration works, because it is easier to read.
-    However, if your code is using GL3+ context, using this may confuse your driver. Please use the GL3 example below.
+    If your code is using GL3+ context or any semi modern OpenGL calls, using this is likely to make everything
-	(You might be able to use this code in a GL3/GL4 context but make sure you disable the programmable 
+    more complicated, will require your code to reset every single OpenGL attributes to their initial state,
-	pipeline by calling "glUseProgram(0)" before ImGui::Render. It appears that many librairies and drivers
+    and might confuse your GPU driver. Prefer using opengl3_example.
-	are having issues mixing GL2 calls and newer GL3/GL4 calls. So it isn't recommended that you use that.)
 
 opengl3_example/
     GLFW + OpenGL example (programmable pipeline, binding modern functions with GL3W).
@@ -74,7 +75,12 @@ apple_example/
     Synergy keyboard integration is rather hacky.
 
 sdl_opengl2_example/
+    *DO NOT USE THIS CODE IF YOUR CODE/ENGINE IS USING MODERN OPENGL*
     SDL2 + OpenGL example (old fixed pipeline).
+    This is mostly provided as a reference to learn how ImGui integration works, because it is easier to read.
+    If your code is using GL3+ context or any semi modern OpenGL calls, using this is likely to make everything
+    more complicated, will require your code to reset every single OpenGL attributes to their initial state,
+    and might confuse your GPU driver. Prefer using sdl_opengl3_example.
 
 sdl_opengl3_example/
     SDL2 + OpenGL3 example.

examples/opengl2_example/imgui_impl_glfw.cpp

@@ -1,10 +1,12 @@
 // ImGui GLFW binding with OpenGL
 // In this binding, ImTextureID is used to store an OpenGL 'GLuint' texture identifier. Read the FAQ about ImTextureID in imgui.cpp.
 
-// If your context or own usage of OpenGL involve anything GL3/GL4, prefer using the code in opengl3_example.
+// *DO NOT USE THIS CODE IF YOUR CODE/ENGINE IS USING MODERN OPENGL*
-// If you are not sure what that means, prefer using the code in opengl3_example.
+// This is mostly provided as a reference to learn how ImGui integration works, because it is easier to read.
-// You *might* use this code with a GL3/GL4 context but make sure you disable the programmable pipeline by calling "glUseProgram(0)" before ImGui::Render().
+// If your code is using GL3+ context or any semi modern OpenGL calls, using this is likely to make everything
-// We cannot do that from GL2 code because the function doesn't exist. Mixing GL2 calls and GL3/GL4 calls is giving trouble to many librairies/drivers.
+// more complicated, will require your code to reset every single OpenGL attributes to their initial state,
+// and might confuse your GPU driver. Prefer using opengl3_example.
+// The GL2 code is unable to reset attributes or even call e.g. "glUseProgram(0)" because they don't exist in that API.
 
 // You can copy and use unmodified imgui_impl_* files in your project. See main.cpp for an example of using this.
 // If you use this binding you'll need to call 4 functions: ImGui_ImplXXXX_Init(), ImGui_ImplXXXX_NewFrame(), ImGui::Render() and ImGui_ImplXXXX_Shutdown().

examples/sdl_opengl2_example/imgui_impl_sdl.cpp

@@ -1,8 +1,12 @@
 // ImGui SDL2 binding with OpenGL
 // In this binding, ImTextureID is used to store an OpenGL 'GLuint' texture identifier. Read the FAQ about ImTextureID in imgui.cpp.
 
-// If your context or own usage of OpenGL involve anything GL3/GL4, prefer using the code in sdl_opengl3_example.
+// *DO NOT USE THIS CODE IF YOUR CODE/ENGINE IS USING MODERN OPENGL*
-// If you are not sure what that means, prefer using the code in sdl_opengl3_example.
+// This is mostly provided as a reference to learn how ImGui integration works, because it is easier to read.
+// If your code is using GL3+ context or any semi modern OpenGL calls, using this is likely to make everything
+// more complicated, will require your code to reset every single OpenGL attributes to their initial state,
+// and might confuse your GPU driver. Prefer using sdl_opengl3_example.
+// The GL2 code is unable to reset attributes or even call e.g. "glUseProgram(0)" because they don't exist in that API.
 
 // You can copy and use unmodified imgui_impl_* files in your project. See main.cpp for an example of using this.
 // If you use this binding you'll need to call 4 functions: ImGui_ImplXXXX_Init(), ImGui_ImplXXXX_NewFrame(), ImGui::Render() and ImGui_ImplXXXX_Shutdown().