Loose improvements to the spatial navigation library.

Espyo · Espyo · commit 4ef748cbc19b · 2025-11-07T17:10:17.000Z
diff --git a/source/source/lib/spatial_navigation/readme.md b/source/source/lib/spatial_navigation/readme.md
@@ -6,6 +6,7 @@ Espyo's GUI spatial navigation algorithm.
 > * [Quick example](#quick-example)
 > * [Features](#features)
 
+
 ## Overview
 
 This is a source-only C++ library that implements a spatial navigation algorithm for graphical user interfaces. The way it works is pretty simple:
@@ -19,6 +20,7 @@ This is a source-only C++ library that implements a spatial navigation algorithm
 
 Spatial navigation is surprisingly tricky. Guessing which GUI item the user wanted to focus is difficult, and depends on the program, the GUI, and more.  There are also a few things that take work to implement, like the ability to loop around once the edge of the GUI is reached, or how to handle GUI items with more items inside. This library aims to ease those burdens.
 
+
 ## Quick example
 
 ```cpp
@@ -41,13 +43,44 @@ void myProgram::doSpatialNavigation(SpatNav::DIRECTION direction) {
 
 ## Features
 
-* Support for looping around the edges of the GUI.
-* Support for parent items that have children items inside.
-* Customizable heuristics.
-* Basic debugging logic.
+* Support for looping around the edges of the GUI (see `Manager::settings`).
+* Support for parent items that have children items that can overflow inside (see `Manager::setParentItem`).
+* Customizable heuristics (see `Manager::heuristics`).
+* Basic debugging logic (see `SPAT_NAV_DEBUG`).
 * Fairly light, and fairly simple.
 * Very agnostic, and with no external dependencies.
-* Unit tests.
+* Simple unit test coverage for the library itself.
+
+
+## Important information
+
+* For simplicity's sake, each item is identified with a `void *`. In your application you probably identify your widgets with an index number or a pointer, so just cast that to a `void *` freely. `nullptr` (zero) is reserved for "none", however.
+* To work with parent and children items:
+  * Note that parent items are never eligible for being focused.
+  * For children items, specify their position in normal GUI coordinates, even if they overflow past the parent's borders.
+* If you don't provide a valid starting point for navigation, it will use 0,0 for the focus position and size. Your users will probably prefer if you pick the first available widget, or the one closest to the mouse cursor.
+
+
+## Troubleshooting
+
+* When looping through an edge of the GUI, it's skipping over an item.
+  * Make sure there's at least a small gap between the items and the edges of the GUI. If it doesn't, you can manually grow the limits by 0.01 without any real drawback.
+* The algorithm is picking the wrong item and I can't understand why.
+  * Try defining `SPAT_NAV_DEBUG` (or uncomment its line near the top of the header file). Then on every frame draw onto the window the contents provided by `Manager::lastNavInfo` in whatever way you want. This should help you understand what the algorithm is doing and what you can customize to make it do what you want.
+* There's an item a bit out of the way, but I can't seem to reach it.
+  * Try `Manager::heuristics::singleLoopPass`.
+
+
+## Inner workings notes
+
+* For parent and children items:
+  * Children items that are overflowing get flattened. In essence the algorithm pretends they exist at the border of the parent, just very very thin.
+  * This approach allows the relative position between items to be kept, whilst also ensuring that navigating into the parent item correctly navigates to the most obvious child item.
+  * Other approaches were possible, but much more complex to implement.
+  * Because of this approach, you have to be wary that while hierarchies can be deeper than one level, the deeper you go the sooner you run into floating-point imprecisions. It should be fine for any normal application though.
+* The algorithm rotates all widgets such that right (positive X) points to the direction of the navigation.
+* Navigation only works in the four cardinal directions. Free angles were considered, but deemed to be way too unreasonable to implement.
+
 
 ## Research
 
diff --git a/source/source/lib/spatial_navigation/spatial_navigation.cpp b/source/source/lib/spatial_navigation/spatial_navigation.cpp
@@ -62,7 +62,7 @@ bool Interface::addItem(void* id, float x, float y, float w, float h) {
  */
 bool Interface::checkHeuristicsPass(
     double itemRelX, double itemRelY, double itemRelW, double itemRelH
-) {
+) const {
     if(
         heuristics.minBlindspotAngle >= 0.0f ||
         heuristics.maxBlindspotAngle >= 0.0f
@@ -171,8 +171,11 @@ void* Interface::doNavigation(
             direction, focusX, focusY, focusW, focusH
         );
         
-    double limitX1, limitY1, limitX2, limitY2;
-    getLimits(&limitX1, &limitY1, &limitX2, &limitY2);
+    double limitX1 = settings.limitX1;
+    double limitY1 = settings.limitY1;
+    double limitX2 = settings.limitX2;
+    double limitY2 = settings.limitY2;
+    getItemLimitsFlattened(&limitX1, &limitY1, &limitX2, &limitY2);
     
     std::map<void*, ItemWithRelUnits> nonLoopedItems;
     std::map<void*, ItemWithRelUnits> loopedItems;
@@ -215,18 +218,14 @@ void* Interface::doNavigation(
  * This only affects children items that are completely outside, not partially.
  */
 void Interface::flattenItems() {
-    if(
-        settings.limitX1 == settings.limitX2 ||
-        settings.limitY1 == settings.limitY2
-    ) {
-        //Malformed limits.
-        for(auto& i : items) {
-            i.second->flatX = i.second->x;
-            i.second->flatY = i.second->y;
-            i.second->flatW = i.second->w;
-            i.second->flatH = i.second->h;
-        }
-        return;
+    double limitX1 = settings.limitX1;
+    double limitY1 = settings.limitY1;
+    double limitX2 = settings.limitX2;
+    double limitY2 = settings.limitY2;
+
+    if(limitX1 == limitX2 || limitY1 == limitY2) {
+        //No specified limits.
+        getItemLimitsNonFlattened(&limitX1, &limitY1, &limitX2, &limitY2);
     }
     
     //Start with the top-level items.
@@ -235,10 +234,7 @@ void Interface::flattenItems() {
         if(getItemParent(i.first)) continue;
         list.push_back(i.second);
     }
-    flattenItemsInList(
-        list,
-        settings.limitX1, settings.limitY1, settings.limitX2, settings.limitY2
-    );
+    flattenItemsInList(list, limitX1, limitY1, limitX2, limitY2);
 }
 
 
@@ -313,7 +309,7 @@ void Interface::flattenItemsInList(
 void Interface::getBestItem(
     const std::map<void*, ItemWithRelUnits>& list,
     double* bestScore, void** bestItemId, bool loopedItems
-) {
+) const {
     for(auto& i : list) {
         if(
             !checkHeuristicsPass(
@@ -353,12 +349,12 @@ void Interface::getBestItem(
  * @param id Identifier of the item whose children to check.
  * @return The children, or an empty vector if none.
  */
-std::vector<Interface::Item*> Interface::getItemChildren(void* id) {
+std::vector<Interface::Item*> Interface::getItemChildren(void* id) const {
     std::vector<Item*> result;
     const auto& it = children.find(id);
     if(it != children.end()) {
         for(size_t c = 0; c < it->second.size(); c++) {
-            result.push_back(items[it->second[c]]);
+            result.push_back(items.at(it->second[c]));
         }
     }
     return result;
@@ -380,7 +376,7 @@ std::vector<Interface::Item*> Interface::getItemChildren(void* id) {
 void Interface::getItemDiffs(
     float focusX, float focusY, float focusW, float focusH,
     Item* iPtr, DIRECTION direction, double* outDiffX, double* outDiffY
-) {
+) const {
     double focusX1 = focusX - focusW / 2.0f;
     double focusY1 = focusY - focusH / 2.0f;
     double focusX2 = focusX + focusW / 2.0f;
@@ -429,6 +425,50 @@ void Interface::getItemDiffs(
 }
 
 
+/**
+ * @brief Returns the limits of all items, using their already-flattened
+ * coordinates.
+ *
+ * @param limitX1 The top-left corner's X coordinate is returned here.
+ * @param limitY1 The top-left corner's Y coordinate is returned here.
+ * @param limitX2 The bottom-right corner's X coordinate is returned here.
+ * @param limitY2 The bottom-right corner's Y coordinate is returned here.
+ */
+void Interface::getItemLimitsFlattened(
+    double* limitX1, double* limitY1, double* limitX2, double* limitY2
+) const {
+    for(const auto& i : items) {
+        Item* iPtr = i.second;
+        *limitX1 = std::min(*limitX1, iPtr->flatX - iPtr->flatW / 2.0f);
+        *limitY1 = std::min(*limitY1, iPtr->flatY - iPtr->flatH / 2.0f);
+        *limitX2 = std::max(*limitX2, iPtr->flatX + iPtr->flatW / 2.0f);
+        *limitY2 = std::max(*limitY2, iPtr->flatY + iPtr->flatH / 2.0f);
+    }
+}
+
+
+/**
+ * @brief Returns the limits of all items, using their normal,
+ * non-flattened coordinates.
+ *
+ * @param limitX1 The top-left corner's X coordinate is returned here.
+ * @param limitY1 The top-left corner's Y coordinate is returned here.
+ * @param limitX2 The bottom-right corner's X coordinate is returned here.
+ * @param limitY2 The bottom-right corner's Y coordinate is returned here.
+ */
+void Interface::getItemLimitsNonFlattened(
+    double* limitX1, double* limitY1, double* limitX2, double* limitY2
+) const {
+    for(const auto& i : items) {
+        Item* iPtr = i.second;
+        *limitX1 = std::min(*limitX1, (double) (iPtr->x - iPtr->w / 2.0f));
+        *limitY1 = std::min(*limitY1, (double) (iPtr->y - iPtr->h / 2.0f));
+        *limitX2 = std::max(*limitX2, (double) (iPtr->x + iPtr->w / 2.0f));
+        *limitY2 = std::max(*limitY2, (double) (iPtr->y + iPtr->h / 2.0f));
+    }
+}
+
+
 /**
  * @brief Converts the standard coordinates of an item to ones relative
  * to the current focus coordinates, and rotated so they're to its right.
@@ -448,7 +488,7 @@ void Interface::getItemRelativeUnits(
     Item* iPtr, DIRECTION direction,
     float focusX, float focusY, float focusW, float focusH,
     double* outRelX, double* outRelY, double* outRelW, double* outRelH
-) {
+) const {
     double resultX = 0.0f;
     double resultY = 0.0f;
     double resultW = 0.0f;
@@ -513,10 +553,10 @@ void Interface::getItemRelativeUnits(
  * @param id Identifier of the item whose parent to check.
  * @return The parent, or nullptr if none.
  */
-Interface::Item* Interface::getItemParent(void* id) {
+Interface::Item* Interface::getItemParent(void* id) const {
     const auto& it = parents.find(id);
     if(it == parents.end()) return nullptr;
-    return items[it->second];
+    return items.at(it->second);
 }
 
 
@@ -531,7 +571,7 @@ Interface::Item* Interface::getItemParent(void* id) {
  */
 double Interface::getItemScore(
     double itemRelX, double itemRelY, double itemRelW, double itemRelH
-) {
+) const {
     switch(heuristics.distCalcMethod) {
     case DIST_CALC_METHOD_EUCLIDEAN: {
         return itemRelX * itemRelX + itemRelY * itemRelY;
@@ -564,7 +604,7 @@ std::map<void*, Interface::ItemWithRelUnits>
 Interface::getItemsWithRelativeUnits(
     DIRECTION direction,
     float focusX, float focusY, float focusW, float focusH
-) {
+) const {
     std::map<void*, Interface::ItemWithRelUnits> result;
     
     for(auto& i : items) {
@@ -589,32 +629,6 @@ Interface::getItemsWithRelativeUnits(
 }
 
 
-/**
- * @brief Returns the limits of the given items.
- *
- * @param limitX1 The top-left corner's X coordinate is returned here.
- * @param limitY1 The top-left corner's Y coordinate is returned here.
- * @param limitX2 The bottom-right corner's X coordinate is returned here.
- * @param limitY2 The bottom-right corner's Y coordinate is returned here.
- */
-void Interface::getLimits(
-    double* limitX1, double* limitY1, double* limitX2, double* limitY2
-) const {
-    *limitX1 = settings.limitX1;
-    *limitY1 = settings.limitY1;
-    *limitX2 = settings.limitX2;
-    *limitY2 = settings.limitY2;
-    
-    for(const auto& i : items) {
-        Item* iPtr = i.second;
-        *limitX1 = std::min(*limitX1, iPtr->flatX - iPtr->flatW / 2.0f);
-        *limitY1 = std::min(*limitY1, iPtr->flatY - iPtr->flatH / 2.0f);
-        *limitX2 = std::max(*limitX2, iPtr->flatX + iPtr->flatW / 2.0f);
-        *limitY2 = std::max(*limitY2, iPtr->flatY + iPtr->flatH / 2.0f);
-    }
-}
-
-
 /**
  * @brief Returns whether an item has children.
  *
diff --git a/source/source/lib/spatial_navigation/spatial_navigation.h b/source/source/lib/spatial_navigation/spatial_navigation.h
@@ -73,15 +73,17 @@ class Interface {
         //--- Members ---
         
         //Top-left corner's X coordinate.
+        //If not specified, i.e. left at the default values, the limits will
+        //be automatically calculated based on the existing items.
         float limitX1 = 0.0f;
         
-        //Top-left corner's Y coordinate.
+        //Same as limitX1, but for the top-left corner's Y coordinate.
         float limitY1 = 0.0f;
         
-        //Bottom-right corner's X coordinate.
+        //Same as limitX1, but for the bottom-right corner's X coordinate.
         float limitX2 = 0.0f;
         
-        //Bottom-right corner's Y coordinate.
+        //Same as limitX1, but for the bottom-right corner's Y coordinate.
         float limitY2 = 0.0f;
         
         //Whether it loops around when it reaches a horizontal limit.
@@ -190,7 +192,7 @@ class Interface {
      * @brief Represents an item in the interface. It can be inside of a parent
      * item.
      */
-    class Item {
+    struct Item {
     
     public:
     
@@ -267,7 +269,7 @@ class Interface {
     
     bool checkHeuristicsPass(
         double itemRelX, double itemRelY, double itemRelW, double itemRelH
-    );
+    ) const;
     bool checkLoopRelativeCoordinates(
         DIRECTION direction, double* itemRelX,
         double limitX1, double limitY1, double limitX2, double limitY2,
@@ -285,26 +287,29 @@ class Interface {
     void getBestItem(
         const std::map<void*, ItemWithRelUnits>& list,
         double* bestScore, void** bestItemId, bool loopedItems
-    );
+    ) const;
     void getItemRelativeUnits(
         Item* iPtr, DIRECTION direction,
         float focusX, float focusY, float focusW, float focusH,
         double* outRelX, double* outRelY, double* outRelW, double* outRelH
-    );
-    std::vector<Item*> getItemChildren(void* id);
+    ) const;
+    std::vector<Item*> getItemChildren(void* id) const;
     void getItemDiffs(
         float focusX, float focusY, float focusW, float focusH,
         Item* iPtr, DIRECTION direction, double* outDiffX, double* outDiffY
-    );
-    Item* getItemParent(void* id);
+    ) const;
+    Item* getItemParent(void* id) const;
     double getItemScore(
         double itemRelX, double itemRelY, double itemRelW, double itemRelH
-    );
+    ) const;
     std::map<void*, ItemWithRelUnits> getItemsWithRelativeUnits(
         DIRECTION direction,
         float focusX, float focusY, float focusW, float focusH
-    );
-    void getLimits(
+    ) const;
+    void getItemLimitsFlattened(
+        double* limitX1, double* limitY1, double* limitX2, double* limitY2
+    ) const;
+    void getItemLimitsNonFlattened(
         double* limitX1, double* limitY1, double* limitX2, double* limitY2
     ) const;
     bool itemHasChildren(void* id) const;
diff --git a/source/source/lib/spatial_navigation/tests/tests_main.cpp b/source/source/lib/spatial_navigation/tests/tests_main.cpp
