Commit | Line | Data |
---|---|---|
3719602c PC |
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). |