api: allow lights.read() to be filtered by light names (#271)

## Link to GitHub Issue, if one exists
Fixes https://github.com/spice2x/spice2x.github.io/issues/179

## Description of change
Previously, lights.read() did not accept any parameters, instead it
returned all lights implemented by the current game.
Problem is that this is too large for some embedded implementations;
also just inefficient.

Add code to accept light names as strings and only return those in the
result.
For performance, use `robin_hood::unordered_map` to speed up the lookup
operation, which was previously a linear search.
Add this to Python wrapper library. Did not bother with others.

Also, as a bonus - update lights.write_reset() to also accept a flat
list of strings, as opposed to array containing a string, which was
silly.

## Compiling
➕ 

## Testing
Tested using spiceremote and writing a short Python program.

src/spice2x/api/modules/lights.cpp

@@ -19,11 +19,16 @@ namespace api::modules {
         functions["read"] = std::bind(&Lights::read, this, _1, _2);
         functions["write"] = std::bind(&Lights::write, this, _1, _2);
         functions["write_reset"] = std::bind(&Lights::write_reset, this, _1, _2);
-        lights = games::get_lights(eamuse_get_game());
+
+        this->lights = games::get_lights(eamuse_get_game());
+        for (auto &light : *this->lights) {
+            this->lights_by_names.emplace(light.getName(), light);
+        }
     }
 
     /**
      * read()
+     * read(name: str, ...)
      */
     void Lights::read(api::Request &req, Response &res) {
 
@@ -32,17 +37,39 @@ namespace api::modules {
             return;
         }
 
-        // add state for each light
-        for (auto &light : *this->lights) {
-            Value state(kArrayType);
-            Value light_name(light.getName().c_str(), res.doc()->GetAllocator());
-            Value light_state(GameAPI::Lights::readLight(RI_MGR, light));
-            Value light_enabled(light.override_enabled);
-            state.PushBack(light_name, res.doc()->GetAllocator());
-            state.PushBack(light_state, res.doc()->GetAllocator());
-            state.PushBack(light_enabled, res.doc()->GetAllocator());
-            res.add_data(state);
+        // all lights for this game
+        if (req.params.Size() == 0) {
+            // add state for each light
+            for (auto &light : *this->lights) {
+                get_light(light, res);
+            }
+
+            return;
         }
+
+        // specified light names
+        for (Value &param : req.params.GetArray()) {
+            // check params
+            if (!param.IsString()) {
+                error_type(res, "name", "string");
+                return;
+            }
+            const auto name = param.GetString();
+            if (this->lights_by_names.contains(name)) {
+                get_light(this->lights_by_names.at(name).get(), res);
+            }
+        }
+    }
+
+    void Lights::get_light(Light &light, Response &res) {
+        Value state(kArrayType);
+        Value light_name(light.getName().c_str(), res.doc()->GetAllocator());
+        Value light_state(GameAPI::Lights::readLight(RI_MGR, light));
+        Value light_enabled(light.override_enabled);
+        state.PushBack(light_name, res.doc()->GetAllocator());
+        state.PushBack(light_state, res.doc()->GetAllocator());
+        state.PushBack(light_enabled, res.doc()->GetAllocator());
+        res.add_data(state);
     }
 
     /**
@@ -90,6 +117,7 @@ namespace api::modules {
 
     /**
      * write_reset()
+     * write_reset(name: str, ...)
      * write_reset([name: str], ...)
      */
     void Lights::write_reset(Request &req, Response &res) {
@@ -119,26 +147,28 @@ namespace api::modules {
 
         // loop parameters
         for (Value &param : req.params.GetArray()) {
+            const char* light_name = nullptr;
 
             // check params
-            if (!param.IsArray()) {
-                error(res, "parameters must be arrays");
-                return;
+            if (param.IsArray()) {
+                if (param.Size() < 1) {
+                    error_params_insufficient(res);
+                    continue;
+                }
+                if (!param[0].IsString()) {
+                    error_type(res, "name", "string");
+                    continue;
+                }
+                // get params
+                light_name = param[0].GetString();
+            } else if (param.IsString()) {
+                light_name = param.GetString();
+            } else {
+                error(res, "parameters must be arrays or strings");
             }
-            if (param.Size() < 1) {
-                error_params_insufficient(res);
-                continue;
-            }
-            if (!param[0].IsString()) {
-                error_type(res, "name", "string");
-                continue;
-            }
-
-            // get params
-            auto light_name = param[0].GetString();
 
             // write analog state
-            if (!this->write_light_reset(light_name)) {
+            if (light_name && !this->write_light_reset(light_name)) {
                 error_unknown(res, "analog", light_name);
                 continue;
             }
@@ -153,21 +183,20 @@ namespace api::modules {
         }
 
         // find light
-        for (auto &light : *this->lights) {
-            if (light.getName() == name) {
-                light.override_state = CLAMP(state, 0.f, 1.f);
-                light.override_enabled = true;
+        if (this->lights_by_names.contains(name)) {
+            auto &light = this->lights_by_names.at(name).get();
+            light.override_state = CLAMP(state, 0.f, 1.f);
+            light.override_enabled = true;
 
-                if (cfg::CONFIGURATOR_STANDALONE) {
-                    GameAPI::Lights::writeLight(RI_MGR, light, state);
-                }
-
-                return true;
+            if (cfg::CONFIGURATOR_STANDALONE) {
+                GameAPI::Lights::writeLight(RI_MGR, light, state);
             }
-        }
 
-        // unknown light
-        return false;
+            return true;
+        } else {
+            // unknown light
+            return false;
+        }
     }
 
     bool Lights::write_light_reset(std::string name) {
@@ -178,14 +207,13 @@ namespace api::modules {
         }
 
         // find light
-        for (auto &light : *this->lights) {
-            if (light.getName() == name) {
-                light.override_enabled = false;
-                return true;
-            }
+        if (this->lights_by_names.contains(name)) {
+            auto &light = this->lights_by_names.at(name).get();
+            light.override_enabled = false;
+            return true;
+        } else {
+            // unknown light
+            return false;
         }
-
-        // unknown light
-        return false;
     }
 }

src/spice2x/api/modules/lights.h

@@ -1,6 +1,8 @@
 #pragma once
 
 #include <vector>
+#include <external/robin_hood.h>
+
 #include "api/module.h"
 #include "api/request.h"
 #include "cfg/api.h"
@@ -15,6 +17,7 @@ namespace api::modules {
 
         // state
         std::vector<Light> *lights;
+        robin_hood::unordered_map<std::string, std::reference_wrapper<Light>> lights_by_names;
 
         // function definitions
         void read(Request &req, Response &res);
@@ -22,6 +25,7 @@ namespace api::modules {
         void write_reset(Request &req, Response &res);
 
         // helper
+        void get_light(Light &light, Response &res);
         bool write_light(std::string name, float state);
         bool write_light_reset(std::string name);
     };