(retroarch.c) Document more

retroarch.c

@@ -126,15 +126,20 @@ static bool take_screenshot_raw(void)
          width, height, -pitch, false);
 }
 
-static void take_screenshot(void)
+/**
+ * take_screenshot:
+ *
+ * Returns: true (1) if successful, otherwise false (0).
+ **/
+static bool take_screenshot(void)
 {
    bool viewport_read = false;
-   bool ret = false;
+   bool ret = true;
    const char *msg = NULL;
 
    /* No way to infer screenshot directory. */
    if ((!*g_settings.screenshot_directory) && (!*g_extern.basename))
-      return;
+      return false;
 
    viewport_read = (g_settings.video.gpu_screenshot ||
          g_extern.system.hw_render_callback.context_type
@@ -180,6 +185,8 @@ static void take_screenshot(void)
 
    if (g_extern.is_paused)
       rarch_render_cached_frame();
+
+   return ret;
 }
 
 void rarch_recording_dump_frame(const void *data, unsigned width,
@@ -245,25 +252,32 @@ void rarch_recording_dump_frame(const void *data, unsigned width,
       driver.recording->push_video(driver.recording_data, &ffemu_data);
 }
 
-static void init_recording(void)
+/**
+ * init_recording:
+ *
+ * Initializes recording.
+ *
+ * Returns: true (1) if successful, otherwise false (0).
+ **/
+static bool init_recording(void)
 {
    struct ffemu_params params = {0};
    const struct retro_system_av_info *info = &g_extern.system.av_info;
 
    if (!g_extern.recording_enable)
-      return;
+      return false;
 
    if (g_extern.libretro_dummy)
    {
       RARCH_WARN(RETRO_LOG_INIT_RECORDING_SKIPPED);
-      return;
+      return false;
    }
 
    if (!g_settings.video.gpu_record
          && g_extern.system.hw_render_callback.context_type)
    {
       RARCH_WARN("Libretro core is hardware rendered. Must use post-shaded recording as well.\n");
-      return;
+      return false;
    }
 
    RARCH_LOG("Custom timing given: FPS: %.4f, Sample rate: %.4f\n",
@@ -288,6 +302,7 @@ static void init_recording(void)
    if (g_settings.video.gpu_record && driver.video->read_viewport)
    {
       struct rarch_viewport vp = {0};
+
       if (driver.video && driver.video->viewport_info)
          driver.video->viewport_info(driver.video_data, &vp);
 
@@ -295,7 +310,7 @@ static void init_recording(void)
       {
          RARCH_ERR("Failed to get viewport information from video driver. "
                "Cannot start recording ...\n");
-         return;
+         return false;
       }
 
       params.out_width  = vp.width;
@@ -320,7 +335,7 @@ static void init_recording(void)
       if (!g_extern.record_gpu_buffer)
       {
          RARCH_ERR("Failed to allocate GPU record buffer.\n");
-         return;
+         return false;
       }
    }
    else
@@ -364,7 +379,11 @@ static void init_recording(void)
    {
       RARCH_ERR(RETRO_LOG_INIT_RECORDING_FAILED);
       rarch_main_command(RARCH_CMD_GPU_RECORD_DEINIT);
+
+      return false;
    }
+
+   return true;
 }
 
 /**
@@ -435,6 +454,11 @@ static void print_features(void)
 }
 #undef _PSUPP
 
+/**
+ * print_compiler:
+ *
+ * Prints compiler that was used for compiling RetroArch.
+ **/
 static void print_compiler(FILE *file)
 {
    fprintf(file, "\nCompiler: ");
@@ -462,6 +486,11 @@ static void print_compiler(FILE *file)
    fprintf(file, "Built: %s\n", __DATE__);
 }
 
+/**
+ * print_help:
+ *
+ * Prints help message explaining RetroArch's commandline switches.
+ **/
 static void print_help(void)
 {
    puts("===================================================================");
@@ -650,6 +679,14 @@ static void set_paths(const char *path)
             sizeof(g_settings.system_directory));
 }
 
+/**
+ * parse_input:
+ * @argc                 : Count of (commandline) arguments.
+ * @argv                 : (Commandline) arguments. 
+ *
+ * Parses (commandline) arguments passed to RetroArch.
+ *
+ **/
 static void parse_input(int argc, char *argv[])
 {
    g_extern.libretro_no_content = false;
@@ -1048,6 +1085,11 @@ static void parse_input(int argc, char *argv[])
             sizeof(g_extern.savestate_dir));
 }
 
+/**
+ * init_controllers:
+ *
+ * Initialize libretro controllers.
+ **/
 static void init_controllers(void)
 {
    unsigned i;
@@ -1223,17 +1265,27 @@ static void init_movie(void)
 #define RARCH_DEFAULT_PORT 55435
 
 #ifdef HAVE_NETPLAY
-static void init_netplay(void)
+/**
+ * init_netplay:
+ *
+ * Initializes netplay.
+ *
+ * If netplay is already initialized, will return false (0).
+ *
+ * Returns: true (1) if successful, otherwise false (0).
+ **/
+
+static bool init_netplay(void)
 {
    struct retro_callbacks cbs = {0};
 
    if (!g_extern.netplay_enable)
-      return;
+      return false;
 
    if (g_extern.bsv.movie_start_playback)
    {
       RARCH_WARN(RETRO_LOG_MOVIE_STARTED_INIT_NETPLAY_FAILED);
-      return;
+      return false;
    }
 
    retro_set_default_callbacks(&cbs);
@@ -1252,16 +1304,17 @@ static void init_netplay(void)
          g_extern.netplay_sync_frames, &cbs, g_extern.netplay_is_spectate,
          g_settings.username);
 
-   if (!driver.netplay_data)
+   if (driver.netplay_data)
-   {
+      return true;
-      g_extern.netplay_is_client = false;
-      RARCH_WARN(RETRO_LOG_INIT_NETPLAY_FAILED);
 
-      if (g_extern.msg_queue)
+   g_extern.netplay_is_client = false;
-         msg_queue_push(g_extern.msg_queue,
+   RARCH_WARN(RETRO_LOG_INIT_NETPLAY_FAILED);
-               RETRO_MSG_INIT_NETPLAY_FAILED,
+
-               0, 180);
+   if (g_extern.msg_queue)
-   }
+      msg_queue_push(g_extern.msg_queue,
+            RETRO_MSG_INIT_NETPLAY_FAILED,
+            0, 180);
+   return false;
 }
 #endif
 
@@ -1318,6 +1371,7 @@ static void init_autosave(void)
 static void deinit_autosave(void)
 {
    unsigned i;
+
    for (i = 0; i < g_extern.num_autosave; i++)
       autosave_free(g_extern.autosave[i]);
 
@@ -1356,7 +1410,9 @@ static void set_savestate_auto_index(void)
 
    for (i = 0; i < dir_list->size; i++)
    {
+      unsigned idx;
       char elem_base[PATH_MAX_LENGTH];
+      const char *end = NULL;
       const char *dir_elem = dir_list->elems[i].data;
 
       fill_pathname_base(elem_base, dir_elem, sizeof(elem_base));
@@ -1364,10 +1420,11 @@ static void set_savestate_auto_index(void)
       if (strstr(elem_base, state_base) != elem_base)
          continue;
 
-      const char *end = dir_elem + strlen(dir_elem);
+      end = dir_elem + strlen(dir_elem);
-      while ((end > dir_elem) && isdigit(end[-1])) end--;
+      while ((end > dir_elem) && isdigit(end[-1]))
+         end--;
 
-      unsigned idx = strtoul(end, NULL, 0);
+      idx = strtoul(end, NULL, 0);
       if (idx > max_idx)
          max_idx = idx;
    }
@@ -1859,6 +1916,7 @@ static void init_system_info(void)
 {
    struct retro_system_info *info = (struct retro_system_info*)
       &g_extern.system.info;
+
    pretro_get_system_info(info);
 
    if (!info->library_name)
@@ -1884,12 +1942,19 @@ static void verify_api_version(void)
 {
    /* TODO - when libretro v2 gets added, allow for switching
     * between libretro version backend dynamically. */
+
    RARCH_LOG("Version of libretro API: %u\n", pretro_api_version());
    RARCH_LOG("Compiled against API: %u\n", RETRO_API_VERSION);
+
    if (pretro_api_version() != RETRO_API_VERSION)
       RARCH_WARN(RETRO_LOG_LIBRETRO_ABI_BREAK);
 }
 
+#define FAIL_CPU(simd_type) do { \
+   RARCH_ERR(simd_type " code is compiled in, but CPU does not support this feature. Cannot continue.\n"); \
+   rarch_fail(1, "validate_cpu_features()"); \
+} while(0)
+
 /* Make sure we haven't compiled for something we cannot run.
  * Ideally, code would get swapped out depending on CPU support, 
  * but this will do for now.
@@ -1899,11 +1964,6 @@ static void validate_cpu_features(void)
    uint64_t cpu = rarch_get_cpu_features();
    (void)cpu;
 
-#define FAIL_CPU(simd_type) do { \
-   RARCH_ERR(simd_type " code is compiled in, but CPU does not support this feature. Cannot continue.\n"); \
-   rarch_fail(1, "validate_cpu_features()"); \
-} while(0)
-
 #ifdef __SSE__
    if (!(cpu & RETRO_SIMD_SSE))
       FAIL_CPU("SSE");
@@ -1970,6 +2030,15 @@ static bool init_core(void)
    return true;
 }
 
+/**
+ * rarch_main_init:
+ * @argc                 : Count of (commandline) arguments.
+ * @argv                 : (Commandline) arguments. 
+ *
+ * Initializes RetroArch.
+ *
+ * Returns: 0 on success, otherwise 1 if there was an error.
+ **/
 int rarch_main_init(int argc, char *argv[])
 {
    int sjlj_ret;
@@ -2026,6 +2095,15 @@ error:
    return 1;
 }
 
+/**
+ * rarch_main_init_wrap:
+ * @args                 : Input arguments.
+ * @argc                 : Count of arguments.
+ * @argv                 : Arguments.
+ *
+ * Generates an @argc and @argv pair based on @args
+ * of type rarch_main_wrap.
+ **/
 void rarch_main_init_wrap(const struct rarch_main_wrap *args,
       int *argc, char **argv)
 {
@@ -2154,9 +2232,14 @@ void rarch_main_set_state(unsigned cmd)
    }
 }
 
-/* Save a new configuration to a file. Filename is based
+/**
- * on heuristics to avoid typing. */
+ * save_core_config:
-
+ *
+ * Saves a new (core) configuration to a file. Filename is based
+ * on heuristics to avoid typing.
+ *
+ * Returns: true (1) on success, otherwise false (0).
+ **/
 static bool save_core_config(void)
 {
    bool ret = false;
@@ -2190,6 +2273,7 @@ static bool save_core_config(void)
       for (i = 0; i < 16; i++)
       {
          char tmp[64];
+
          fill_pathname_base(config_name, g_settings.libretro,
                sizeof(config_name));
          path_remove_extension(config_name);
@@ -2243,6 +2327,14 @@ static bool save_core_config(void)
    return ret;
 }
 
+/**
+ * rarch_main_command:
+ * @cmd                  : Command index.
+ *
+ * Performs RetroArch command with index @cmd.
+ *
+ * Returns: true (1) on success, otherwise false (0).
+ **/
 bool rarch_main_command(unsigned cmd)
 {
    unsigned i   = 0;
@@ -2328,7 +2420,8 @@ bool rarch_main_command(unsigned cmd)
          main_state(cmd);
          break;
       case RARCH_CMD_TAKE_SCREENSHOT:
-         take_screenshot();
+         if (!take_screenshot())
+            return false;
          break;
       case RARCH_CMD_PREPARE_DUMMY:
          *g_extern.fullpath = '\0';
@@ -2506,7 +2599,8 @@ bool rarch_main_command(unsigned cmd)
          break;
       case RARCH_CMD_RECORD_INIT:
          rarch_main_command(RARCH_CMD_HISTORY_DEINIT);
-         init_recording();
+         if (!init_recording())
+            return false;
          break;
       case RARCH_CMD_HISTORY_DEINIT:
          if (g_defaults.history)
@@ -2741,7 +2835,7 @@ bool rarch_main_command(unsigned cmd)
       case RARCH_CMD_NETPLAY_INIT:
          rarch_main_command(RARCH_CMD_NETPLAY_DEINIT);
 #ifdef HAVE_NETPLAY
-         init_netplay();
+         return init_netplay();
 #endif
          break;
       case RARCH_CMD_NETPLAY_FLIP_PLAYERS:
@@ -2885,6 +2979,11 @@ bool rarch_main_command(unsigned cmd)
    return true;
 }
 
+/**
+ * rarch_main_deinit:
+ *
+ * Deinitializes RetroArch.
+ **/
 void rarch_main_deinit(void)
 {
    rarch_main_command(RARCH_CMD_NETPLAY_DEINIT);
@@ -2911,6 +3010,13 @@ void rarch_main_deinit(void)
    g_extern.main_is_init = false;
 }
 
+/**
+ * rarch_playlist_load_content:
+ * @playlist             : Playlist handle.
+ * @idx                  : Index in playlist.
+ *
+ * Initializes core and loads content based on playlist entry.
+ **/
 void rarch_playlist_load_content(content_playlist_t *playlist,
       unsigned idx)
 {
@@ -2929,9 +3035,22 @@ void rarch_playlist_load_content(content_playlist_t *playlist,
    rarch_main_command(RARCH_CMD_LOAD_CORE);
 }
 
-/* When selection is presented back, returns 0.
+/**
- * If it can make a decision right now, returns -1. */
+ * rarch_defer_core:
-
+ * @core_info            : Core info list handle.
+ * @dir                  : Directory. Gets joined with @path.
+ * @path                 : Path. Gets joined with @dir.
+ * @menu_label           : Label identifier of menu setting.
+ * @deferred_path        : Deferred core path. Will be filled in
+ *                         by function.
+ * @sizeof_deferred_path : Size of @deferred_path.
+ *
+ * Gets deferred core.
+ *
+ * Returns: 0 if there are multiple deferred cores and a 
+ * selection needs to be made from a list, otherwise
+ * returns -1 and fills in @deferred_path with path to core.
+ **/
 int rarch_defer_core(core_info_list_t *core_info, const char *dir,
       const char *path, const char *menu_label,
       char *deferred_path, size_t sizeof_deferred_path)
@@ -2962,21 +3081,20 @@ int rarch_defer_core(core_info_list_t *core_info, const char *dir,
       supported = 1;
    }
    else
-   {
       strlcpy(new_core_path, info->path, sizeof(new_core_path));
-   }
 
-   /* Can make a decision right now. */
+   /* There are multiple deferred cores and a 
-   if (supported == 1)
+    * selection needs to be made from a list, return 0. */
-   {
+   if (supported != 1)
-      strlcpy(g_extern.fullpath, deferred_path,
+      return 0;
-            sizeof(g_extern.fullpath));
+
-      if (path_file_exists(new_core_path))
+   strlcpy(g_extern.fullpath, deferred_path,
-         strlcpy(g_settings.libretro, new_core_path,
+         sizeof(g_extern.fullpath));
-               sizeof(g_settings.libretro));
+
-      return -1;
+   if (path_file_exists(new_core_path))
-   }
+      strlcpy(g_settings.libretro, new_core_path,
-   return 0;
+            sizeof(g_settings.libretro));
+   return -1;
 }
 
 /**

retroarch.h

@@ -26,36 +26,60 @@ extern "C" {
 enum basic_event
 {
    RARCH_CMD_NONE = 0,
+   /* Resets RetroArch. */
    RARCH_CMD_RESET,
+   /* Loads content file. */
    RARCH_CMD_LOAD_CONTENT,
    RARCH_CMD_LOAD_CONTENT_PERSIST,
    RARCH_CMD_LOAD_CORE,
    RARCH_CMD_LOAD_STATE,
    RARCH_CMD_SAVE_STATE,
+   /* Takes screenshot. */
    RARCH_CMD_TAKE_SCREENSHOT,
+   /* Initializes dummy core. */
    RARCH_CMD_PREPARE_DUMMY,
+   /* Quits RetroArch. */
    RARCH_CMD_QUIT,
+   /* Reinitialize all drivers. */
    RARCH_CMD_REINIT,
+   /* Deinitialize rewind. */
    RARCH_CMD_REWIND_DEINIT,
+   /* Initializes rewind. */
    RARCH_CMD_REWIND_INIT,
+   /* Toggles rewind. */
    RARCH_CMD_REWIND_TOGGLE,
+   /* Deinitializes autosave. */
    RARCH_CMD_AUTOSAVE_DEINIT,
+   /* Initializes autosave. */
    RARCH_CMD_AUTOSAVE_INIT,
    RARCH_CMD_AUTOSAVE_STATE,
+   /* Stops audio. */
    RARCH_CMD_AUDIO_STOP,
+   /* Starts audio. */
    RARCH_CMD_AUDIO_START,
+   /* Mutes audio. */
    RARCH_CMD_AUDIO_MUTE_TOGGLE,
+   /* Initializes overlay. */
    RARCH_CMD_OVERLAY_INIT,
+   /* Deinitializes overlay. */
    RARCH_CMD_OVERLAY_DEINIT,
    RARCH_CMD_OVERLAY_SET_SCALE_FACTOR,
    RARCH_CMD_OVERLAY_SET_ALPHA_MOD,
+   /* Cycle to next overlay. */
    RARCH_CMD_OVERLAY_NEXT,
+   /* Initializes graphics filter. */
    RARCH_CMD_DSP_FILTER_INIT,
+   /* Deinitializes graphics filter. */
    RARCH_CMD_DSP_FILTER_DEINIT,
+   /* Deinitializes GPU recoring. */
    RARCH_CMD_GPU_RECORD_DEINIT,
+   /* Initializes recording system. */
    RARCH_CMD_RECORD_INIT,
+   /* Deinitializes recording system. */
    RARCH_CMD_RECORD_DEINIT,
+   /* Deinitializes history playlist. */
    RARCH_CMD_HISTORY_DEINIT,
+   /* Initializes history playlist. */
    RARCH_CMD_HISTORY_INIT,
    RARCH_CMD_CORE_INFO_DEINIT,
    RARCH_CMD_CORE_INFO_INIT,
@@ -66,21 +90,33 @@ enum basic_event
    RARCH_CMD_VIDEO_APPLY_STATE_CHANGES,
    RARCH_CMD_VIDEO_SET_BLOCKING_STATE,
    RARCH_CMD_VIDEO_SET_NONBLOCKING_STATE,
+   /* Sets current aspect ratio index. */
    RARCH_CMD_VIDEO_SET_ASPECT_RATIO,
    RARCH_CMD_RESET_CONTEXT,
+   /* Restarts RetroArch. */
    RARCH_CMD_RESTART_RETROARCH,
+   /* Force-quit RetroArch. */
    RARCH_CMD_QUIT_RETROARCH,
+   /* Resume RetroArch when in menu. */
    RARCH_CMD_RESUME,
+   /* Toggles pause. */
    RARCH_CMD_PAUSE_TOGGLE,
+   /* Pauses RetroArch. */
    RARCH_CMD_UNPAUSE,
+   /* Unpauses retroArch. */
    RARCH_CMD_PAUSE,
    RARCH_CMD_PAUSE_CHECKS,
    RARCH_CMD_MENU_SAVE_CONFIG,
    RARCH_CMD_MENU_PAUSE_LIBRETRO,
+   /* Toggles menu on/off. */
    RARCH_CMD_MENU_TOGGLE,
+   /* Applies shader changes. */
    RARCH_CMD_SHADERS_APPLY_CHANGES,
+   /* Initializes shader directory. */
    RARCH_CMD_SHADER_DIR_INIT,
+   /* Deinitializes shader directory. */
    RARCH_CMD_SHADER_DIR_DEINIT,
+   /* Initializes controllers. */
    RARCH_CMD_CONTROLLERS_INIT,
    RARCH_CMD_SAVEFILES,
    RARCH_CMD_SAVEFILES_INIT,
@@ -89,25 +125,43 @@ enum basic_event
    RARCH_CMD_MSG_QUEUE_DEINIT,
    RARCH_CMD_CHEATS_INIT,
    RARCH_CMD_CHEATS_DEINIT,
+   /* Initializes netplay system. */
    RARCH_CMD_NETPLAY_INIT,
+   /* Deinitializes netplay system. */
    RARCH_CMD_NETPLAY_DEINIT,
+   /* Flip netplay players. */
    RARCH_CMD_NETPLAY_FLIP_PLAYERS,
+   /* Initializes BSV movie. */
    RARCH_CMD_BSV_MOVIE_INIT,
+   /* Deinitializes BSV movie. */
    RARCH_CMD_BSV_MOVIE_DEINIT,
+   /* Initializes command interface. */
    RARCH_CMD_COMMAND_INIT,
+   /* Deinitialize command interface. */
    RARCH_CMD_COMMAND_DEINIT,
+   /* Deinitializes drivers. */
    RARCH_CMD_DRIVERS_DEINIT,
+   /* Initializes drivers. */
    RARCH_CMD_DRIVERS_INIT,
+   /* Reinitializes audio driver. */
    RARCH_CMD_AUDIO_REINIT,
+   /* Resizes windowed scale. Will reinitialize video driver. */
    RARCH_CMD_RESIZE_WINDOWED_SCALE,
+   /* Deinitializes temporary content. */
    RARCH_CMD_TEMPORARY_CONTENT_DEINIT,
    RARCH_CMD_SUBSYSTEM_FULLPATHS_DEINIT,
    RARCH_CMD_LOG_FILE_DEINIT,
+   /* Toggles disk eject. */
    RARCH_CMD_DISK_EJECT_TOGGLE,
+   /* Cycle to next disk. */
    RARCH_CMD_DISK_NEXT,
+   /* Cycle to previous disk. */
    RARCH_CMD_DISK_PREV,
+   /* Stops rumbling. */
    RARCH_CMD_RUMBLE_STOP,
+   /* Toggles mouse grab. */
    RARCH_CMD_GRAB_MOUSE_TOGGLE,
+   /* Toggles fullscreen mode. */
    RARCH_CMD_FULLSCREEN_TOGGLE,
    RARCH_CMD_PERFCNT_REPORT_FRONTEND_LOG,
 };
@@ -141,13 +195,44 @@ void rarch_main_state_free(void);
 
 void rarch_main_set_state(unsigned action);
 
+/**
+ * rarch_main_command:
+ * @cmd                  : Command index.
+ *
+ * Performs RetroArch command with index @cmd.
+ *
+ * Returns: true (1) on success, otherwise false (0).
+ **/
 bool rarch_main_command(unsigned action);
 
+/**
+ * rarch_main_init:
+ * @argc                 : Count of (commandline) arguments.
+ * @argv                 : (Commandline) arguments. 
+ *
+ * Initializes RetroArch.
+ *
+ * Returns: 0 on success, otherwise 1 if there was an error.
+ **/
 int rarch_main_init(int argc, char *argv[]);
 
+/**
+ * rarch_main_init_wrap:
+ * @args                 : Input arguments.
+ * @argc                 : Count of arguments.
+ * @argv                 : Arguments.
+ *
+ * Generates an @argc and @argv pair based on @args
+ * of type rarch_main_wrap.
+ **/
 void rarch_main_init_wrap(const struct rarch_main_wrap *args,
       int *argc, char **argv);
 
+/**
+ * rarch_main_deinit:
+ *
+ * Deinitializes RetroArch.
+ **/
 void rarch_main_deinit(void);
 
 /**
@@ -208,9 +293,32 @@ void rarch_recording_dump_frame(const void *data, unsigned width,
  **/
 bool rarch_replace_config(const char *path);
 
+/**
+ * rarch_playlist_load_content:
+ * @playlist             : Playlist handle.
+ * @idx                  : Index in playlist.
+ *
+ * Initializes core and loads content based on playlist entry.
+ **/
 void rarch_playlist_load_content(content_playlist_t *playlist,
       unsigned index);
 
+/**
+ * rarch_defer_core:
+ * @core_info            : Core info list handle.
+ * @dir                  : Directory. Gets joined with @path.
+ * @path                 : Path. Gets joined with @dir.
+ * @menu_label           : Label identifier of menu setting.
+ * @deferred_path        : Deferred core path. Will be filled in
+ *                         by function.
+ * @sizeof_deferred_path : Size of @deferred_path.
+ *
+ * Gets deferred core.
+ *
+ * Returns: 0 if there are multiple deferred cores and a 
+ * selection needs to be made from a list, otherwise
+ * returns -1 and fills in @deferred_path with path to core.
+ **/
 int rarch_defer_core(core_info_list_t *data,
       const char *dir, const char *path, const char *menu_label,
       char *deferred_path, size_t sizeof_deferred_path);