deps/libretro-common/samples/core_options/README.md

   1 ## Adding 'enhanced' core options to a core
   2
   3 The basic steps for updating a core to support core options v1 are as follows:
   4
   5 - Copy `example_default/libretro_core_options.h` to the same directory as `libretro.c/.cpp`
   6
   7 - Copy `example_default/libretro_core_options_intl.h` to the same directory as `libretro.c/.cpp`
   8
   9 - Add `#include "libretro_core_options.h"` to `libretro.c/.cpp`
  10
  11 - Replace any existing calls of `RETRO_ENVIRONMENT_SET_VARIABLES` with `libretro_set_core_options(retro_environment_t environ_cb)`
  12   (Note: `libretro_set_core_options()` should be called as early as possible - preferably in `retro_set_environment()`
  13   and no later than `retro_load_game()`)
  14
  15 - Open `libretro_core_options.h` and replace the contents of the existing `option_defs_us` struct array with all required core option parameters.
  16
  17 ## Adding core option translations
  18
  19 To add a translation, simply:
  20
  21 - Copy the contents of `option_defs_us` *from* `libretro_core_options.h` *to* `libretro_core_options_intl.h` into a new struct array with the appropriate language suffix
  22
  23 - Translate all human-readable strings
  24
  25 - Add the new struct array to the appropriate location in the `option_defs_intl` array inside `libretro_core_options.h`
  26
  27 This is most easily understood by considering the example in `example_translation/`. Here a French translation has been added (`option_defs_fr`), with comments explaining the appropriate formatting requirements.
  28
  29 NOTE: Since translations involve the use of UTF-8 characters, `libretro_core_options_intl.h` must include a BOM marker. *This renders translations incompatible with c89 builds*. When performing a c89 build, the flag `HAVE_NO_LANGEXTRA` *must* be defined (e.g. `-DHAVE_NO_LANGEXTRA`). This will disable all translations.
  30
  31 ## Disabling core options on unsupported frontends
  32
  33 Sometimes it is desirable to only show a particular core option if the frontend supports the new core options v1 API. For example:
  34
  35 - The API v1 allows cores to hide options dynamically
  36
  37 - We can therefore create a specific 'toggle display' option to hide or show a number of other options (e.g. advanced settings)
  38
  39 - On frontends that do not support API v1, this 'toggle display' option will have no function - it should therefore be omitted
  40
  41 This can be handled easily by editing the `libretro_set_core_options()` function to ignore certain core name (key) values when generating option variable arrays for old-style frontends. Again, this is most easily understood by considering the example in `example_hide_option/libretro_core_options.h`:
  42
  43 - Here, a `mycore_show_speedhacks` option is added to `option_defs_us`
  44
  45 - On line 227, the following comparison allows the option to be skipped:
  46   (Note that another `strcmp()` may be added for each option to be omitted)
  47
  48 ```c
  49 if (strcmp(key, "mycore_show_speedhacks") == 0)
  50         continue;
  51 ```
  52
  53 For any cores that require this functionality, `example_hide_option/libretro_core_options.h` should be used as a template in place of `example_default/libretro_core_options.h`
  54
  55 ## Adding core option categories
  56
  57 Core options v2 adds a mechanism for assigning categories to options. On supported fontends, options of a particular category will be displayed in a submenu/subsection of the main core options menu. This functionality may be used to reduce visual clutter, or to effectively 'hide' advanced settings without requiring a dedicated 'toggle display' option.
  58
  59 A template for enabling categories via the core options v2 interface is provided in `example_categories`. The usage of this code is identical to that described in the `Adding 'enhanced' core options to a core` section, with one addition: the `libretro_set_core_options()` function here includes an additional argument identifying whether the frontend has option category support (a core may wish to selectively hide or reorganise options based upon this variable).