Examples Readme and Changelog tweaks, added #2527, re-ordered examples/README alphabetically.

examples/README.txt

@@ -91,7 +91,7 @@ Most the example bindings are split in 2 parts:
      This is counter-intuitive, but this will get you running faster! Once you better understand how imgui
      works and is bound, you can rewrite the code using your own systems.
 
- - Road-map: Dear ImGui 1.70 (WIP currently in the "viewport" branch) will allows imgui windows to be
+ - Road-map: Dear ImGui 1.80 (WIP currently in the "docking" branch) will allows imgui windows to be
    seamlessly detached from the main application window. This is achieved using an extra layer to the
    platform and renderer bindings, which allows imgui to communicate platform-specific requests.
    If you decide to use unmodified imgui_impl_xxxx.cpp files, you will automatically benefit from
@@ -101,7 +101,7 @@ Most the example bindings are split in 2 parts:
 List of Platforms Bindings in this repository:
 
     imgui_impl_glfw.cpp       ; GLFW (Windows, macOS, Linux, etc.) http://www.glfw.org/
-    imgui_impl_osx.mm         ; macOS native API
+    imgui_impl_osx.mm         ; macOS native API (not as feature complete as glfw/sdl back-ends)
     imgui_impl_sdl.cpp        ; SDL2 (Windows, macOS, Linux, iOS, Android) https://www.libsdl.org
     imgui_impl_win32.cpp      ; Win32 native API (Windows)
     imgui_impl_glut.cpp       ; GLUT/FreeGLUT (not recommended unless really miss the 90's)
@@ -122,7 +122,7 @@ List of high-level Frameworks Bindings in this repository: (combine Platform + R
     imgui_impl_allegro5.cpp
     imgui_impl_marmalade.cpp
 
-Note that Dear ImGui works with Emscripten. 
+Note that Dear ImGui works with Emscripten.
 The examples_emscripten/ app uses sdl.cpp + opengl3.cpp but other combinations are possible.
 Third-party framework, graphics API and languages bindings are listed at:
 
@@ -151,40 +151,33 @@ Building:
   directly with a command-line compiler.
 
 
-example_win32_directx9/
-    DirectX9 example, Windows only.
-    = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx9.cpp
-
-example_win32_directx10/
-    DirectX10 example, Windows only.
-    = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx10.cpp
-
-example_win32_directx11/
-    DirectX11 example, Windows only.
-    = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx11.cpp
-
-example_win32_directx12/
-    DirectX12 example, Windows only.
-    = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx12.cpp
-    This is quite long and tedious, because: DirectX12.
+example_allegro5/
+    Allegro 5 example.
+    = main.cpp + imgui_impl_allegro5.cpp
 
 example_apple_metal/
     OSX & iOS + Metal.
     = main.m + imgui_impl_osx.mm + imgui_impl_metal.mm
     It is based on the "cross-platform" game template provided with Xcode as of Xcode 9.
-    (NB: you may still want to use GLFW or SDL which will also support Windows, Linux along with OSX.)
+    (NB: imgui_impl_osx.mm is currently not as feature complete as other platforms back-ends.
+    You may prefer to use the GLFW Or SDL back-ends, which will also support Windows and Linux.)
 
 example_apple_opengl2/
     OSX + OpenGL2.
     = main.mm + imgui_impl_osx.mm + imgui_impl_opengl2.cpp
-    (NB: you may still want to use GLFW or SDL which will also support Windows, Linux along with OSX.)
+    (NB: imgui_impl_osx.mm is currently not as feature complete as other platforms back-ends.
+    You may prefer to use the GLFW Or SDL back-ends, which will also support Windows and Linux.)
 
 example_empscripten:
     Emcripten + SDL2 + OpenGL3+/ES2/ES3 example.
     = main.cpp + imgui_impl_sdl.cpp + imgui_impl_opengl3.cpp
-    Note that other examples based on SDL or GLFW + GL could easily be modified to work with Emscripten.
+    Note that other examples based on SDL or GLFW + OpenGL could easily be modified to work with Emscripten.
     We provide this to make the Emscripten differences obvious, and have them not pollute all other examples.
 
+example_glfw_metal/
+    GLFW (Mac) + Vulkan example.
+    = main.mm + imgui_impl_glfw.cpp + imgui_impl_metal.mm.
+
 example_glfw_opengl2/
     GLFW + OpenGL2 example (legacy, fixed pipeline).
     = main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl2.cpp
@@ -200,12 +193,24 @@ example_glfw_opengl3/
     = main.cpp + imgui_impl_glfw.cpp + imgui_impl_opengl3.cpp
     This uses more modern OpenGL calls and custom shaders.
     Prefer using that if you are using modern OpenGL in your application (anything with shaders).
+    (Please be mindful that accessing OpenGL3+ functions requires a function loader, which are a frequent
+    source for confusion for new users. We use a loader in imgui_impl_opengl3.cpp which may be different
+    from the one your app normally use. Read imgui_impl_opengl3.h for details and how to change it.)
 
 example_glfw_vulkan/
     GLFW (Win32, Mac, Linux) + Vulkan example.
     = main.cpp + imgui_impl_glfw.cpp + imgui_impl_vulkan.cpp
     This is quite long and tedious, because: Vulkan.
 
+example_glut_opengl2/
+    GLUT (e.g., FreeGLUT on Linux/Windows, GLUT framework on OSX) + OpenGL2.
+    = main.cpp + imgui_impl_glut.cpp + imgui_impl_opengl2.cpp
+    Note that GLUT/FreeGLUT is largely obsolete software, prefer using GLFW or SDL.
+
+example_marmalade/
+    Marmalade example using IwGx.
+    = main.cpp + imgui_impl_marmalade.cpp
+
 example_sdl_opengl2/
     SDL2 (Win32, Mac, Linux etc.) + OpenGL example (legacy, fixed pipeline).
     = main.cpp + imgui_impl_sdl.cpp + imgui_impl_opengl2.cpp
@@ -221,20 +226,28 @@ example_sdl_opengl3/
     = main.cpp + imgui_impl_sdl.cpp + imgui_impl_opengl3.cpp
     This uses more modern OpenGL calls and custom shaders.
     Prefer using that if you are using modern OpenGL in your application (anything with shaders).
+    (Please be mindful that accessing OpenGL3+ functions requires a function loader, which are a frequent
+    source for confusion for new users. We use a loader in imgui_impl_opengl3.cpp which may be different
+    from the one your app normally use. Read imgui_impl_opengl3.h for details and how to change it.)
 
 example_sdl_vulkan/
     SDL2 (Win32, Mac, Linux, etc.) + Vulkan example.
     = main.cpp + imgui_impl_sdl.cpp + imgui_impl_vulkan.cpp
     This is quite long and tedious, because: Vulkan.
 
-example_allegro5/
-    Allegro 5 example.
-    = main.cpp + imgui_impl_allegro5.cpp
+example_win32_directx9/
+    DirectX9 example, Windows only.
+    = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx9.cpp
 
-example_glut_opengl2/
-    GLUT (e.g., FreeGLUT on Linux/Windows, GLUT framework on OSX) + OpenGL2.
-    = main.cpp + imgui_impl_glut.cpp + imgui_impl_opengl2.cpp
+example_win32_directx10/
+    DirectX10 example, Windows only.
+    = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx10.cpp
 
-example_marmalade/
-    Marmalade example using IwGx.
-    = main.cpp + imgui_impl_marmalade.cpp
+example_win32_directx11/
+    DirectX11 example, Windows only.
+    = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx11.cpp
+
+example_win32_directx12/
+    DirectX12 example, Windows only.
+    = main.cpp + imgui_impl_win32.cpp + imgui_impl_dx12.cpp
+    This is quite long and tedious, because: DirectX12.

examples/example_glut_opengl2/main.cpp

@@ -3,6 +3,7 @@
 
 // !!! GLUT/FreeGLUT IS OBSOLETE SOFTWARE. Using GLUT is not recommended unless you really miss the 90's. !!!
 // !!! If someone or something is teaching you GLUT in 2019, you are being abused. Please show some resistance. !!!
+// !!! Prefer using GLFW Or SDL instead!
 
 #include "imgui.h"
 #include "../imgui_impl_glut.h"

examples/imgui_impl_glut.cpp

@@ -3,6 +3,7 @@
 
 // !!! GLUT/FreeGLUT IS OBSOLETE SOFTWARE. Using GLUT is not recommended unless you really miss the 90's. !!!
 // !!! If someone or something is teaching you GLUT in 2019, you are being abused. Please show some resistance. !!!
+// !!! Prefer using GLFW or SDL instead!
 
 // Issues:
 //  [ ] Platform: GLUT is unable to distinguish e.g. Backspace from CTRL+H or TAB from CTRL+I

examples/imgui_impl_glut.h

@@ -3,6 +3,7 @@
 
 // !!! GLUT/FreeGLUT IS OBSOLETE SOFTWARE. Using GLUT is not recommended unless you really miss the 90's. !!!
 // !!! If someone or something is teaching you GLUT in 2019, you are being abused. Please show some resistance. !!!
+// !!! Prefer using GLFW or SDL instead!
 
 // Issues:
 //  [ ] Platform: GLUT is unable to distinguish e.g. Backspace from CTRL+H or TAB from CTRL+I