Fonts: Added some details about using custom colorful icons.

imgui.h

@@ -2077,11 +2077,14 @@ struct ImFontAtlas
     IMGUI_API const ImWchar*    GetGlyphRangesVietnamese();             // Default + Vietname characters
 
     //-------------------------------------------
-    // Custom Rectangles/Glyphs API
+    // [BETA] Custom Rectangles/Glyphs API
     //-------------------------------------------
 
-    // You can request arbitrary rectangles to be packed into the atlas, for your own purposes. After calling Build(), you can query the rectangle position and render your pixels.
-    // You can also request your rectangles to be mapped as font glyph (given a font + Unicode point), so you can render e.g. custom colorful icons and use them as regular glyphs.
+    // You can request arbitrary rectangles to be packed into the atlas, for your own purposes. 
+    // After calling Build(), you can query the rectangle position and render your pixels.
+    // You can also request your rectangles to be mapped as font glyph (given a font + Unicode point), 
+    // so you can render e.g. custom colorful icons and use them as regular glyphs.
+    // Read misc/fonts/README.txt for more details about using colorful icons.
     struct CustomRect
     {
         unsigned int    ID;             // Input    // User ID. Use <0x10000 to map into a font glyph, >=0x10000 for other/internal/custom texture data.
@@ -2093,7 +2096,6 @@ struct ImFontAtlas
         CustomRect()            { ID = 0xFFFFFFFF; Width = Height = 0; X = Y = 0xFFFF; GlyphAdvanceX = 0.0f; GlyphOffset = ImVec2(0,0); Font = NULL; }
         bool IsPacked() const   { return X != 0xFFFF; }
     };
-
     IMGUI_API int       AddCustomRectRegular(unsigned int id, int width, int height);                                                                   // Id needs to be >= 0x10000. Id >= 0x80000000 are reserved for ImGui and ImDrawList
     IMGUI_API int       AddCustomRectFontGlyph(ImFont* font, ImWchar id, int width, int height, float advance_x, const ImVec2& offset = ImVec2(0,0));   // Id needs to be < 0x10000 to register a rectangle to map into a specific font.
     const CustomRect*   GetCustomRectByIndex(int index) const { if (index < 0) return NULL; return &CustomRects[index]; }

misc/fonts/README.txt

@@ -26,6 +26,7 @@ If you have other loading/merging/adding fonts, you can post on the Dear ImGui "
 - Fonts Loading Instructions
 - FreeType rasterizer, Small font sizes
 - Building Custom Glyph Ranges
+- Using custom colorful icons
 - Embedding Fonts in Source Code
 - Credits/Licences for fonts included in this folder
 - Fonts Links
@@ -198,6 +199,43 @@ For example: for a game where your script is known, if you can feed your entire
   io.Fonts->Build();                                     // Build the atlas while 'ranges' is still in scope and not deleted.
 
 
+---------------------------------------
+ USING CUSTOM COLORFUL ICONS
+---------------------------------------
+
+(This is a BETA api, use if you are familiar with dear imgui and with your rendering back-end)
+
+You can use the ImFontAtlas::AddCustomRect() and ImFontAtlas::AddCustomRectFontGlyph() api to register rectangles
+that will be packed into the font atlas texture. Register them before building the atlas, then call Build().
+You can then use ImFontAtlas::GetCustomRectByIndex(int) to query the position/size of your rectangle within the
+texture, and blit/copy any graphics data of your choice into those rectangles.
+
+Pseudo-code:
+
+  // Add font, then register one custom 13x13 rectangle mapped to glyph 'a' of this font
+  ImFont* font = io.Fonts->AddFontDefault();
+  int rect_id = io.Fonts->AddCustomRectFontGlyph(font, 'a', 13, 13, 13+1);
+
+  // Build atlas
+  io.Fonts->Build();
+
+  // Retrieve texture in RGBA format
+  unsigned char* tex_pixels = NULL;
+  int tex_width, tex_height;
+  io.Fonts->GetTexDataAsRGBA32(&tex_pixels, &tex_width, &tex_height);
+
+  // Fill the custom rectangle with red pixels (in reality you would draw/copy your bitmap data here)
+  if (const ImFontAtlas::CustomRect* rect = io.Fonts->GetCustomRectByIndex(rect_id))
+  {
+      for (int y = 0; y < rect->Height; y++)
+      {
+          ImU32* p = (ImU32*)tex_pixels + (rect->Y + y) * tex_width + (rect->X);
+          for (int x = rect->Width; x > 0; x--)
+              *p++ = IM_COL32(255, 0, 0, 255);
+      }
+  }
+
+
 ---------------------------------------
  EMBEDDING FONTS IN SOURCE CODE
 ---------------------------------------