feat: per-Index color/size support with ImPlot3DSpec (#182)

Feat: Per-Index Color/Size Support with ImPlot3DSpec

Author: brenocq

example/CMakeLists.txt

@@ -26,7 +26,7 @@ FetchContent_MakeAvailable(glfw)
 FetchContent_Declare(
     imgui
     GIT_REPOSITORY "https://github.com/ocornut/imgui"
-    GIT_TAG "v1.92.4"
+    GIT_TAG "v1.92.7"
     GIT_PROGRESS TRUE
 )
 FetchContent_MakeAvailable(imgui)

implot3d.cpp

@@ -48,6 +48,16 @@ Below is a change-log of API breaking changes only. If you are using one of the
 When you are not sure about an old symbol or function name, try using the Search/Find function of your IDE to look for comments or references in all
 implot3d files. You can read releases logs https://github.com/brenocq/implot3d/releases for more details.
 
+- 2026/04/04 (0.4) - PlotMesh signature changed: the ImPlot3DPoint* overload is deprecated and will be removed in v1.0.
+                     A new overload accepting separate coordinate arrays (vtx_xs, vtx_ys, vtx_zs) was added, matching
+                     the pattern of PlotLine/PlotScatter/PlotTriangle and supporting Spec.Offset and Spec.Stride.
+                         ```cpp
+                         // Before
+                         ImPlot3D::PlotMesh("Mesh", vtx, idxs, vtx_count, idx_count);
+
+                         // After
+                         ImPlot3D::PlotMesh("Mesh", vtx_xs, vtx_ys, vtx_zs, idxs, vtx_count, idx_count);
+                         ```
 - 2026/02/03 (0.4) - ImPlotSpec was made the default and _only_ way of styling plot items. The SetNextXXXStyle functions have been removed.
                       - SetNextLineStyle has been removed, styling should be set via ImPlot3DSpec.
                           ```cpp
@@ -631,7 +641,7 @@ float ComputeMaxTickLabelExtent(const ImPlot3DAxis& axis);
 
 // Spacing constants for axis tick labels and axis labels
 static const float AXIS_TICK_INNER_PAD = 5.0f;  // gap between axis edge and inner edge of tick labels
-static const float AXIS_LABEL_PAD      = 10.0f; // gap between tick label outer edge and axis label center
+static const float AXIS_LABEL_PAD = 10.0f;      // gap between tick label outer edge and axis label center
 static const float AXIS_RECT_MIN_WIDTH = 40.0f; // minimum hover rect width when labels are absent
 
 // Computes the total outward width of the hover rect for an axis
@@ -2898,7 +2908,7 @@ struct ImPlot3DStyleVarInfo {
 static const ImPlot3DStyleVarInfo GPlot3DStyleVarInfo[] = {
     // Item style
     {ImGuiDataType_Float, 1, (ImU32)offsetof(ImPlot3DStyle, LineWeight)}, // ImPlot3DStyleVar_LineWeight
-    {ImGuiDataType_S32,   1, (ImU32)offsetof(ImPlot3DStyle, Marker)},     // ImPlot3DStyleVar_Marker
+    {ImGuiDataType_S32, 1, (ImU32)offsetof(ImPlot3DStyle, Marker)},       // ImPlot3DStyleVar_Marker
     {ImGuiDataType_Float, 1, (ImU32)offsetof(ImPlot3DStyle, MarkerSize)}, // ImPlot3DStyleVar_MarkerSize
     {ImGuiDataType_Float, 1, (ImU32)offsetof(ImPlot3DStyle, FillAlpha)},  // ImPlot3DStyleVar_FillAlpha
 

implot3d.h

@@ -103,17 +103,22 @@ typedef ImTextureID ImTextureRef;
 
 // Plotting properties. These provide syntactic sugar for creating ImPlot3DSpec from (ImPlot3DProp,value) pairs
 enum ImPlot3DProp_ {
-    ImPlot3DProp_LineColor,       // Line color; IMPLOT3D_AUTO_COL will use next Colormap color
-    ImPlot3DProp_LineWeight,      // Line weight in pixels
-    ImPlot3DProp_FillColor,       // Fill color (applies to shaded regions); IMPLOT3D_AUTO_COL will use next Colormap color
-    ImPlot3DProp_FillAlpha,       // Alpha multiplier (applies to FillColor and MarkerFillColor)
-    ImPlot3DProp_Marker,          // Marker type
-    ImPlot3DProp_MarkerSize,      // Size of markers (radius) *in pixels*
-    ImPlot3DProp_MarkerLineColor, // Marker outline color; IMPLOT3D_AUTO_COL will use next LineColor
-    ImPlot3DProp_MarkerFillColor, // Marker fill color; IMPLOT3D_AUTO_COL will use LineColor
-    ImPlot3DProp_Offset,          // Data index offset
-    ImPlot3DProp_Stride,          // Data stride in bytes; IMPLOT3D_AUTO will result in sizeof(T) where T is the type passed to PlotX
-    ImPlot3DProp_Flags            // Optional item flags; can be composed from common ImPlot3DItemFlags and/or specialized ImPlot3DXFlags
+    ImPlot3DProp_LineColor,        // Line color; IMPLOT3D_AUTO_COL will use next Colormap color
+    ImPlot3DProp_LineColors,       // Array of line colors (ImU32*); if nullptr, use LineColor for all
+    ImPlot3DProp_LineWeight,       // Line weight in pixels
+    ImPlot3DProp_FillColor,        // Fill color (applies to shaded regions); IMPLOT3D_AUTO_COL will use next Colormap color
+    ImPlot3DProp_FillColors,       // Array of fill colors (ImU32*); if nullptr, use FillColor for all
+    ImPlot3DProp_FillAlpha,        // Alpha multiplier (applies to FillColor, FillColors, MarkerFillColor, and MarkerFillColors)
+    ImPlot3DProp_Marker,           // Marker type
+    ImPlot3DProp_MarkerSize,       // Size of markers (radius) *in pixels*
+    ImPlot3DProp_MarkerSizes,      // Array of marker sizes (float*); if nullptr, use MarkerSize for all
+    ImPlot3DProp_MarkerLineColor,  // Marker outline color; IMPLOT3D_AUTO_COL will use next LineColor
+    ImPlot3DProp_MarkerLineColors, // Array of marker outline colors (ImU32*); if nullptr, use MarkerLineColor for all
+    ImPlot3DProp_MarkerFillColor,  // Marker fill color; IMPLOT3D_AUTO_COL will use LineColor
+    ImPlot3DProp_MarkerFillColors, // Array of marker fill colors (ImU32*); if nullptr, use MarkerFillColor for all
+    ImPlot3DProp_Offset,           // Data index offset
+    ImPlot3DProp_Stride,           // Data stride in bytes; IMPLOT3D_AUTO will result in sizeof(T) where T is the type passed to PlotX
+    ImPlot3DProp_Flags             // Optional item flags; can be composed from common ImPlot3DItemFlags and/or specialized ImPlot3DXFlags
 };
 
 // Flags for ImPlot3D::BeginPlot()
@@ -378,13 +383,18 @@ enum ImPlot3DColormap_ {
 //    });
 struct ImPlot3DSpec {
     ImVec4 LineColor = IMPLOT3D_AUTO_COL;        // Line color; IMPLOT3D_AUTO_COL will use next Colormap color
+    ImU32* LineColors = nullptr;                 // Per-index line colors; if nullptr, use LineColor for all
     float LineWeight = 1.0f;                     // Line weight in pixels
     ImVec4 FillColor = IMPLOT3D_AUTO_COL;        // Fill color (applies to shaded regions); IMPLOT3D_AUTO_COL will use next Colormap color
-    float FillAlpha = IMPLOT3D_AUTO;             // Alpha multiplier (applies to FillColor and MarkerFillColor)
+    ImU32* FillColors = nullptr;                 // Per-index fill colors; if nullptr, use FillColor for all
+    float FillAlpha = IMPLOT3D_AUTO;             // Alpha multiplier (applies to FillColor, FillColors, MarkerFillColor, and MarkerFillColors)
     ImPlot3DMarker Marker = ImPlot3DMarker_Auto; // Marker type
     float MarkerSize = IMPLOT3D_AUTO;            // Size of markers (radius) *in pixels*
+    float* MarkerSizes = nullptr;                // Per-index marker sizes; if nullptr, use MarkerSize for all
     ImVec4 MarkerLineColor = IMPLOT3D_AUTO_COL;  // Marker outline color; IMPLOT3D_AUTO_COL will use LineColor
+    ImU32* MarkerLineColors = nullptr;           // Per-index marker outline colors; if nullptr, use MarkerLineColor for all
     ImVec4 MarkerFillColor = IMPLOT3D_AUTO_COL;  // Marker fill color; IMPLOT3D_AUTO_COL will use LineColor
+    ImU32* MarkerFillColors = nullptr;           // Per-index marker fill colors; if nullptr, use MarkerFillColor for all
     int Offset = 0;                              // Data index offset
     int Stride = IMPLOT3D_AUTO;                  // Data stride in bytes; IMPLOT3D_AUTO will result in sizeof(T) where T is the type passed to PlotX
     ImPlot3DItemFlags Flags =
@@ -426,6 +436,27 @@ struct ImPlot3DSpec {
         IM_ASSERT(0 && "User provided an ImPlot3DProp which cannot be set from scalar value!");
     }
 
+    // Set a property from an ImU32* array (per-index colors).
+    void SetProp(ImPlot3DProp prop, ImU32* v) {
+        switch (prop) {
+            case ImPlot3DProp_LineColors: LineColors = v; return;
+            case ImPlot3DProp_FillColors: FillColors = v; return;
+            case ImPlot3DProp_MarkerLineColors: MarkerLineColors = v; return;
+            case ImPlot3DProp_MarkerFillColors: MarkerFillColors = v; return;
+            default: break;
+        }
+        IM_ASSERT(0 && "User provided an ImPlot3DProp which cannot be set from ImU32* value!");
+    }
+
+    // Set a property from a float* array (per-index sizes).
+    void SetProp(ImPlot3DProp prop, float* v) {
+        switch (prop) {
+            case ImPlot3DProp_MarkerSizes: MarkerSizes = v; return;
+            default: break;
+        }
+        IM_ASSERT(0 && "User provided an ImPlot3DProp which cannot be set from float* value!");
+    }
+
     // Set a property from an ImVec4 value.
     void SetProp(ImPlot3DProp prop, const ImVec4& v) {
         switch (prop) {
@@ -620,9 +651,18 @@ IMPLOT3D_TMP void PlotQuad(const char* label_id, const T* xs, const T* ys, const
 IMPLOT3D_TMP void PlotSurface(const char* label_id, const T* xs, const T* ys, const T* zs, int x_count, int y_count, double scale_min = 0.0,
                               double scale_max = 0.0, const ImPlot3DSpec& spec = ImPlot3DSpec());
 
-// Plots a 3D mesh given vertex positions and indices. Triangles are defined by the index buffer (every 3 indices form a triangle)
-IMPLOT3D_API void PlotMesh(const char* label_id, const ImPlot3DPoint* vtx, const unsigned int* idx, int vtx_count, int idx_count,
-                           const ImPlot3DSpec& spec = ImPlot3DSpec());
+// Plots a 3D mesh given vertex positions as separate coordinate arrays and an index buffer.
+// Triangles are defined by the index buffer (every 3 indices form a triangle).
+// Spec.Offset and Spec.Stride apply to the vertex coordinate arrays only, not to the index buffer.
+// Color array semantics:
+//   - FillColors / LineColors:          idx_count entries, indexed by position in the index buffer.
+//                                       Each triangle has 3 consecutive color entries (one per corner).
+//                                       Setting all 3 to the same value gives flat per-triangle shading.
+//                                       Setting different values enables Gouraud shading (GPU-interpolated).
+//                                       To shade by vertex, map: FillColors[i] = vtx_colors[idxs[i]].
+//   - MarkerFillColors / MarkerLineColors: vtx_count entries, one per unique vertex.
+IMPLOT3D_TMP void PlotMesh(const char* label_id, const T* vtx_xs, const T* vtx_ys, const T* vtx_zs, const unsigned int* idxs, int vtx_count,
+                           int idx_count, const ImPlot3DSpec& spec = ImPlot3DSpec());
 
 // Plots a rectangular image in 3D defined by its center and two direction vectors (axes).
 // #center is the center of the rectangle in plot coordinates.
@@ -1011,8 +1051,7 @@ struct ImPlot3DStyle {
     // Constructor
     IMPLOT3D_API ImPlot3DStyle();
     ImPlot3DStyle(const ImPlot3DStyle& other) = default;
-    ImPlot3DStyle& operator=(const ImPlot3DStyle& other) =
-  default;
+    ImPlot3DStyle& operator=(const ImPlot3DStyle& other) = default;
 };
 
 //-----------------------------------------------------------------------------
@@ -1069,16 +1108,26 @@ extern unsigned int duck_idx[DUCK_IDX_COUNT];  // Duck indices
 namespace ImPlot3D {
 
 // OBSOLETED in v0.4 (from February 2026)
-// IMPLOT_API void SetNextLineStyle(const ImVec4& col = IMPLOT_AUTO_COL, float weight = IMPLOT_AUTO); // OBSOLETED IN v0.4 // Set ImPlotSpec.LineColor/LineWeight or construct ImPlotSpec with { ImPlotSpec_LineColor, color, ImPlotSpec_LineWeight, weight }.
+// IMPLOT_API void SetNextLineStyle(const ImVec4& col = IMPLOT_AUTO_COL, float weight = IMPLOT_AUTO); // OBSOLETED IN v0.4 // Set
+// ImPlotSpec.LineColor/LineWeight or construct ImPlotSpec with { ImPlotSpec_LineColor, color, ImPlotSpec_LineWeight, weight }.
 
-// IMPLOT_API void SetNextFillStyle(const ImVec4& col = IMPLOT_AUTO_COL, float alpha_mod = IMPLOT_AUTO);// OBSOLETED IN v0.4 // Set ImPlotSpec.FillColor/FillAlpha or construct ImPlotSpec with { ImPlotSpec_FillColor, color, ImPlotSpec_FillAlpha, alpha }.
+// IMPLOT_API void SetNextFillStyle(const ImVec4& col = IMPLOT_AUTO_COL, float alpha_mod = IMPLOT_AUTO);// OBSOLETED IN v0.4 // Set
+// ImPlotSpec.FillColor/FillAlpha or construct ImPlotSpec with { ImPlotSpec_FillColor, color, ImPlotSpec_FillAlpha, alpha }.
 
-// IMPLOT_API void SetNextMarkerStyle(ImPlotMarker marker = IMPLOT_AUTO, float size = IMPLOT_AUTO, const ImVec4& fill = IMPLOT_AUTO_COL, float weight = IMPLOT_AUTO, const ImVec4& outline = IMPLOT_AUTO_COL); // OBSOLETED IN v0.4 // Set ImPlotSpec.Marker/MarkerSize/MarkerFillColor/LineWeight/MarkerLineColor or construct ImPlotSpec with { ImPlotSpec_Marker, marker, ImPlotSpec_MarkerSize, size, ImPlotSpec_MarkerFillColor, fill_color, ImPlotSpec_LineWeight, weight, ImPlotSpec_MarkerLineColor, outline }.
+// IMPLOT_API void SetNextMarkerStyle(ImPlotMarker marker = IMPLOT_AUTO, float size = IMPLOT_AUTO, const ImVec4& fill = IMPLOT_AUTO_COL, float weight
+// = IMPLOT_AUTO, const ImVec4& outline = IMPLOT_AUTO_COL); // OBSOLETED IN v0.4 // Set
+// ImPlotSpec.Marker/MarkerSize/MarkerFillColor/LineWeight/MarkerLineColor or construct ImPlotSpec with { ImPlotSpec_Marker, marker,
+// ImPlotSpec_MarkerSize, size, ImPlotSpec_MarkerFillColor, fill_color, ImPlotSpec_LineWeight, weight, ImPlotSpec_MarkerLineColor, outline }.
 
 // OBSOLETED in v0.3 -> PLANNED REMOVAL in v1.0
 IMPLOT3D_DEPRECATED(IMPLOT3D_API ImVec2 GetPlotPos());  // Renamed to GetPlotRectPos()
 IMPLOT3D_DEPRECATED(IMPLOT3D_API ImVec2 GetPlotSize()); // Renamed to GetPlotRectSize()
 
+// OBSOLETED in v0.4 -> PLANNED REMOVAL in v1.0
+// Use PlotMesh(label_id, vtx_xs, vtx_ys, vtx_zs, idx, vtx_count, idx_count, spec) instead.
+IMPLOT3D_DEPRECATED(IMPLOT3D_API void PlotMesh(const char* label_id, const ImPlot3DPoint* vtx, const unsigned int* idxs, int vtx_count, int idx_count,
+                                               const ImPlot3DSpec& spec = ImPlot3DSpec()));
+
 } // namespace ImPlot3D
 
 #endif // #ifndef IMPLOT3D_DISABLE_OBSOLETE_FUNCTIONS