consolidate and comment input_remapping.h

input/input_driver.h

@@ -524,46 +524,6 @@ struct input_keyboard_ctx_wait
 void input_keyboard_event(bool down, unsigned code, uint32_t character,
       uint16_t mod, unsigned device);
 
-const char *input_config_bind_map_get_base(unsigned i);
-
-unsigned input_config_bind_map_get_meta(unsigned i);
-
-const char *input_config_bind_map_get_desc(unsigned i);
-
-uint8_t input_config_bind_map_get_retro_key(unsigned i);
-
-/* auto_bind can be NULL. */
-void input_config_get_bind_string(char *buf,
-      const struct retro_keybind *bind,
-      const struct retro_keybind *auto_bind, size_t size);
-
-/**
- * input_config_translate_str_to_rk:
- * @str                            : String to translate to key ID.
- *
- * Translates string representation to key identifier.
- *
- * Returns: key identifier.
- **/
-enum retro_key input_config_translate_str_to_rk(const char *str);
-
-/**
- * input_config_translate_str_to_bind_id:
- * @str                            : String to translate to bind ID.
- *
- * Translate string representation to bind ID.
- *
- * Returns: Bind ID value on success, otherwise
- * RARCH_BIND_LIST_END on not found.
- **/
-unsigned input_config_translate_str_to_bind_id(const char *str);
-
-void config_read_keybinds_conf(void *data);
-
-/* Note: 'data' is an object of type config_file_t
- * > We assume it was done like this to avoid including
- *   config_file.h... */
-void input_config_set_autoconfig_binds(unsigned port, void *data);
 
 /* Set input_device_info */
 void input_config_set_device_name(unsigned port, const char *name);

input/input_remapping.h

@@ -26,56 +26,162 @@
 RETRO_BEGIN_DECLS
 
 /**
- * input_remapping_load_file:
- * @data                     : Path to config file.
- *
  * Loads a remap file from disk to memory.
  * 
- * Returns: true (1) if successful, otherwise false (0).
+ * @param data Path to config file.
+ *
+ * @return true (1) if successful, otherwise false (0).
  **/
 bool input_remapping_load_file(void *data, const char *path);
 
 /**
- * input_remapping_save_file:
- * @path                     : Path to remapping file (relative path).
- *
  * Saves remapping values to file.
  *
- * Returns: true (1) if successful, otherwise false (0).
+ * @param path Relative path to remapping file.
+ *
+ * @return true (1) if successful, otherwise false (0).
  **/
 bool input_remapping_save_file(const char *path);
 
 bool input_remapping_remove_file(const char *path, 
                                  const char *dir_input_remapping);
 
-/* Caches any global configuration settings that
+/**
- * should not be overwritten by input remap
+ * Caches any global configuration settings that should not be overwritten by
- * changes made while content is running.
+ * input remap changes made while content is running. Must be called on each
- * Must be called on each core init. */
+ * core init. 
+ */
 void input_remapping_cache_global_config(void);
-/* Sets flags to enable the restoration of
+
- * global configuration settings from the
+/**
- * internal cache. Should be called independently
+ * Sets flags to enable the restoration of global configuration settings from
- * from 'input_remapping_cache_global_config()'.
+ * the internal cache. Should be called independently from 
+ * `input_remapping_cache_global_config()`.
  * Must be called:
  *   - Whenever content is loaded
- * - Whenever a remap file is loaded */
+ *   - Whenever a remap file is loaded 
+ */
 void input_remapping_enable_global_config_restore(void);
-/* Restores any cached global configuration settings
+
- * *if* 'input_remapping_enable_global_config_restore()'
+/**
- * has been called.
+ * Restores any global configuration settings that were cached on the last core
- * Must be called on core deint.
+ * init if `input_remapping_enable_global_config_restore()` has been called.
- * If 'clear_cache' is true, function becomes a NOOP
+ * Must be called on core deinitialization. 
- * until the next time input_remapping_cache_global_config()
+ * 
- * and input_remapping_enable_global_config_restore()
+ * @param clear_cache  If true, function becomes a NOOP until the next time
- * are called. */
+ *                     `input_remapping_cache_global_config()` and 
+ *                     `input_remapping_enable_global_config_restore()` are
+ *                     called.
+ */
 void input_remapping_restore_global_config(bool clear_cache);
 
+/**
+ * Must be called whenever `settings->uints.input_remap_ports` is modified.
+ */
 void input_remapping_update_port_map(void);
 
+/**
+ * Frees global->name.remapfile and sets these runloop_state flags to false: 
+ * remaps_core_active, remaps_content_dir_active, and remaps_game_active.
+ */
 void input_remapping_deinit(void);
+
+/**
+ * Used to set the default mapping values within the `settings` struct
+ * @param clear_cache  This value is passed to 
+ *                     `input_remapping_restore_global_config()`. Please see
+ *                     the documentation for that function for details.
+ */
 void input_remapping_set_defaults(bool clear_cache);
 
+/**
+ * Checks `input_config_bind_map` for the requested `input_bind_map`, and if
+ * the bind has been registered, returns its base.
+ * 
+ * @param index
+ * 
+ * @return the contents of the meta field, or NULL if there is no matching bind
+ */
+const char *input_config_bind_map_get_base(unsigned bind_index);
+
+/**
+ * Checks `input_config_bind_map` for the requested `input_bind_map`, and if
+ * the bind has been registered, returns the value of its meta binds field.
+ *
+ * @param index
+ *
+ * @return the contents of the meta field, or 0 if there is no matching bind
+ */
+unsigned input_config_bind_map_get_meta(unsigned bind_index);
+
+/**
+ * Checks `input_config_bind_map` for the requested `input_bind_map`, and if
+ * the bind has been registered, returns a pointer to its description field.
+ * 
+ * @param index
+ * 
+ * @return the contents of the description field, or NULL if there is no
+ *         matching bind
+ */
+const char *input_config_bind_map_get_desc(unsigned index);
+
+/**
+ * Checks `input_config_bind_map` for the requested `input_bind_map`, and if
+ * the bind has been registered, returns the value of its retro_key field.
+ * 
+ * @param index
+ * 
+ * @return the value of the retro_key field, or 0 if there is no matching bind
+ */
+uint8_t input_config_bind_map_get_retro_key(unsigned index);
+
+/**
+ * Converts a retro_keybind to a human-readable string, optionally allowing a
+ * fallback auto_bind to be used as the source for the string. 
+ *
+ * @param buf        A string which will be overwritten with the returned value
+ * @param bind       A binding to convert to a string
+ * @param auto_bind  A default binding which will be used after `bind`. Can be NULL.
+ * @param size       The maximum length that will be written to `buf`
+ */
+void input_config_get_bind_string(char *buf, const struct retro_keybind *bind,
+      const struct retro_keybind *auto_bind, size_t size);
+
+/**
+ * Parses the string representation of a retro_key struct
+ * 
+ * @param str String to parse.
+ *
+ * @return Key identifier.
+ **/
+enum retro_key input_config_translate_str_to_rk(const char *str);
+
+/**
+ * Searches for a string among the "base" fields of the list of binds.
+ * 
+ * @param str String to search for among the binds
+ *
+ * @return Bind index value on success or RARCH_BIND_LIST_END if not found.
+ **/
+unsigned input_config_translate_str_to_bind_id(const char *str);
+
+/**
+ * Parse the bind data of an object of config_file_t.
+ *
+ * @param data  An object of type config_file_t. We assume it is passed as a
+ *              void pointer like this to avoid including config_file.h.
+ **/
+void config_read_keybinds_conf(void *data);
+
+/**
+ * Apply autoconfig binds to the indicated control port.
+ * 
+ * @param port
+ * @param data  An object of type config_file_t. We assume it is passed as a
+ *              void pointer like this to avoid including config_file.h.
+ */
+void input_config_set_autoconfig_binds(unsigned port, void *data);
+
 RETRO_END_DECLS
 
 #endif

menu/cbs/menu_cbs_scan.c

@@ -24,6 +24,7 @@
 #include "../menu_driver.h"
 #include "../menu_cbs.h"
 #include "../menu_setting.h"
+#include "../../input/input_remapping.h"
 
 #include "../../input/input_driver.h"
 

menu/cbs/menu_cbs_sublabel.c

@@ -21,6 +21,7 @@
 
 #include "../menu_driver.h"
 #include "../menu_cbs.h"
+#include "../../input/input_remapping.h"
 
 #include "../../retroarch.h"
 #include "../../core_option_manager.h"

menu/menu_displaylist.c

@@ -112,6 +112,7 @@
 #include "../manual_content_scan.h"
 #include "../core_backup.h"
 #include "../misc/cpufreq/cpufreq.h"
+#include "../input/input_remapping.h" 
 
 /* Spacers used for '<content> - <core name>' labels
  * in playlists */

retroarch.c

@@ -26510,46 +26510,46 @@ void input_keyboard_event(bool down, unsigned code,
    }
 }
 
-static bool input_config_bind_map_get_valid(unsigned i)
+static bool input_config_bind_map_get_valid(unsigned bind_index)
 {
    const struct input_bind_map *keybind =
-      (const struct input_bind_map*)INPUT_CONFIG_BIND_MAP_GET(i);
+      (const struct input_bind_map*)INPUT_CONFIG_BIND_MAP_GET(bind_index);
    if (!keybind)
       return false;
    return keybind->valid;
 }
 
-unsigned input_config_bind_map_get_meta(unsigned i)
+unsigned input_config_bind_map_get_meta(unsigned bind_index)
 {
    const struct input_bind_map *keybind =
-      (const struct input_bind_map*)INPUT_CONFIG_BIND_MAP_GET(i);
+      (const struct input_bind_map*)INPUT_CONFIG_BIND_MAP_GET(bind_index);
    if (!keybind)
       return 0;
    return keybind->meta;
 }
 
-const char *input_config_bind_map_get_base(unsigned i)
+const char *input_config_bind_map_get_base(unsigned bind_index)
 {
    const struct input_bind_map *keybind =
-      (const struct input_bind_map*)INPUT_CONFIG_BIND_MAP_GET(i);
+      (const struct input_bind_map*)INPUT_CONFIG_BIND_MAP_GET(bind_index);
    if (!keybind)
       return NULL;
    return keybind->base;
 }
 
-const char *input_config_bind_map_get_desc(unsigned i)
+const char *input_config_bind_map_get_desc(unsigned bind_index)
 {
    const struct input_bind_map *keybind =
-      (const struct input_bind_map*)INPUT_CONFIG_BIND_MAP_GET(i);
+      (const struct input_bind_map*)INPUT_CONFIG_BIND_MAP_GET(bind_index);
    if (!keybind)
       return NULL;
    return msg_hash_to_str(keybind->desc);
 }
 
-uint8_t input_config_bind_map_get_retro_key(unsigned i)
+uint8_t input_config_bind_map_get_retro_key(unsigned bind_index)
 {
    const struct input_bind_map *keybind =
-      (const struct input_bind_map*)INPUT_CONFIG_BIND_MAP_GET(i);
+      (const struct input_bind_map*)INPUT_CONFIG_BIND_MAP_GET(bind_index);
    if (!keybind)
       return 0;
    return keybind->retro_key;

tasks/task_autodetect.c

@@ -30,6 +30,7 @@
 #include "../list_special.h"
 #include "../retroarch.h"
 #include "../input/input_driver.h"
+#include "../input/input_remapping.h"
 
 #include "tasks_internal.h"
 #ifdef HAVE_BLISSBOX

tasks/task_overlay.c

@@ -28,6 +28,7 @@
 #include "tasks_internal.h"
 
 #include "../input/input_overlay.h"
+#include "../input/input_remapping.h"
 #include "../retroarch.h"
 #include "../verbosity.h"
 

ui/drivers/qt/qt_options.cpp

@@ -14,6 +14,7 @@ extern "C" {
 
 #include "../../../gfx/video_display_server.h"
 #include "../../../input/input_driver.h"
+#include "../../../input/input_remapping.h"
 #include "../../../network/netplay/netplay.h"
 #include "../../../retroarch.h"