[pcsx_rearmed.git] / deps / libretro-common / samples / core_options / README.md

## Adding 'enhanced' core options to a core

The basic steps for updating a core to support core options v1 are as follows:

- Copy `example_default/libretro_core_options.h` to the same directory as `libretro.c/.cpp`

- Copy `example_default/libretro_core_options_intl.h` to the same directory as `libretro.c/.cpp`

- Add `#include "libretro_core_options.h"` to `libretro.c/.cpp`

- Replace any existing calls of `RETRO_ENVIRONMENT_SET_VARIABLES` with `libretro_set_core_options(retro_environment_t environ_cb)`  
  (Note: `libretro_set_core_options()` should be called as early as possible - preferably in `retro_set_environment()`  
  and no later than `retro_load_game()`)

- Open `libretro_core_options.h` and replace the contents of the existing `option_defs_us` struct array with all required core option parameters.  

## Adding core option translations

To add a translation, simply:

- 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

- Translate all human-readable strings

- Add the new struct array to the appropriate location in the `option_defs_intl` array inside `libretro_core_options.h`

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.

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.

## Disabling core options on unsupported frontends

Sometimes it is desirable to only show a particular core option if the frontend supports the new core options v1 API. For example:

- The API v1 allows cores to hide options dynamically

- We can therefore create a specific 'toggle display' option to hide or show a number of other options (e.g. advanced settings)

- On frontends that do not support API v1, this 'toggle display' option will have no function - it should therefore be omitted

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`:

- Here, a `mycore_show_speedhacks` option is added to `option_defs_us`

- On line 227, the following comparison allows the option to be skipped:  
  (Note that another `strcmp()` may be added for each option to be omitted)

```c
if (strcmp(key, "mycore_show_speedhacks") == 0)
	continue;
```

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`

## Adding core option categories

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.

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).
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).