Skip to content

Commit 65efce1

Browse files
jdgleaverjdgleaver
committed
Update libretro.h (disk control interface v1)
1 parent 6419cc4 commit 65efce1

1 file changed

Lines changed: 121 additions & 11 deletions

File tree

‎include/libretro.h‎

Lines changed: 121 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1117,7 +1117,7 @@ enum retro_mod
11171117
* This may be still be done regardless of the core options
11181118
* interface version.
11191119
*
1120-
* If version is 1 however, core options may instead be set by
1120+
* If version is >= 1 however, core options may instead be set by
11211121
* passing an array of retro_core_option_definition structs to
11221122
* RETRO_ENVIRONMENT_SET_CORE_OPTIONS, or a 2D array of
11231123
* retro_core_option_definition structs to RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL.
@@ -1132,8 +1132,8 @@ enum retro_mod
11321132
* GET_VARIABLE.
11331133
* This allows the frontend to present these variables to
11341134
* a user dynamically.
1135-
* This should only be called if RETRO_ENVIRONMENT_GET_ENHANCED_CORE_OPTIONS
1136-
* returns an API version of 1.
1135+
* This should only be called if RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION
1136+
* returns an API version of >= 1.
11371137
* This should be called instead of RETRO_ENVIRONMENT_SET_VARIABLES.
11381138
* This should be called the first time as early as
11391139
* possible (ideally in retro_set_environment).
@@ -1169,8 +1169,6 @@ enum retro_mod
11691169
* i.e. it should be feasible to cycle through options
11701170
* without a keyboard.
11711171
*
1172-
* First entry should be treated as a default.
1173-
*
11741172
* Example entry:
11751173
* {
11761174
* "foo_option",
@@ -1196,8 +1194,8 @@ enum retro_mod
11961194
* GET_VARIABLE.
11971195
* This allows the frontend to present these variables to
11981196
* a user dynamically.
1199-
* This should only be called if RETRO_ENVIRONMENT_GET_ENHANCED_CORE_OPTIONS
1200-
* returns an API version of 1.
1197+
* This should only be called if RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION
1198+
* returns an API version of >= 1.
12011199
* This should be called instead of RETRO_ENVIRONMENT_SET_VARIABLES.
12021200
* This should be called the first time as early as
12031201
* possible (ideally in retro_set_environment).
@@ -1257,7 +1255,38 @@ enum retro_mod
12571255
*
12581256
* 'data' points to an unsigned variable
12591257
*/
1260-
1258+
1259+
#define RETRO_ENVIRONMENT_GET_DISK_CONTROL_INTERFACE_VERSION 57
1260+
/* unsigned * --
1261+
* Unsigned value is the API version number of the disk control
1262+
* interface supported by the frontend. If callback return false,
1263+
* API version is assumed to be 0.
1264+
*
1265+
* In legacy code, the disk control interface is defined by passing
1266+
* a struct of type retro_disk_control_callback to
1267+
* RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE.
1268+
* This may be still be done regardless of the disk control
1269+
* interface version.
1270+
*
1271+
* If version is >= 1 however, the disk control interface may
1272+
* instead be defined by passing a struct of type
1273+
* retro_disk_control_ext_callback to
1274+
* RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE.
1275+
* This allows the core to provide additional information about
1276+
* disk images to the frontend and/or enables extra
1277+
* disk control functionality by the frontend.
1278+
*/
1279+
1280+
#define RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE 58
1281+
/* const struct retro_disk_control_ext_callback * --
1282+
* Sets an interface which frontend can use to eject and insert
1283+
* disk images, and also obtain information about individual
1284+
* disk image files registered by the core.
1285+
* This is used for games which consist of multiple images and
1286+
* must be manually swapped out by the user (e.g. PSX, floppy disk
1287+
* based systems).
1288+
*/
1289+
12611290
/* VFS functionality */
12621291

12631292
/* File paths:
@@ -2307,7 +2336,8 @@ struct retro_keyboard_callback
23072336
retro_keyboard_event_t callback;
23082337
};
23092338

2310-
/* Callbacks for RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE.
2339+
/* Callbacks for RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE &
2340+
* RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE.
23112341
* Should be set for implementations which can swap out multiple disk
23122342
* images in runtime.
23132343
*
@@ -2365,6 +2395,53 @@ typedef bool (RETRO_CALLCONV *retro_replace_image_index_t)(unsigned index,
23652395
* with replace_image_index. */
23662396
typedef bool (RETRO_CALLCONV *retro_add_image_index_t)(void);
23672397

2398+
/* Sets initial image to insert in drive when calling
2399+
* core_load_game().
2400+
* Since we cannot pass the initial index when loading
2401+
* content (this would require a major API change), this
2402+
* is set by the frontend *before* calling the core's
2403+
* retro_load_game()/retro_load_game_special() implementation.
2404+
* A core should therefore cache the index/path values and handle
2405+
* them inside retro_load_game()/retro_load_game_special().
2406+
* - If 'index' is invalid (index >= get_num_images()), the
2407+
* core should ignore the set value and instead use 0
2408+
* - 'path' is used purely for error checking - i.e. when
2409+
* content is loaded, the core should verify that the
2410+
* disk specified by 'index' has the specified file path.
2411+
* This is to guard against auto selecting the wrong image
2412+
* if (for example) the user should modify an existing M3U
2413+
* playlist. We have to let the core handle this because
2414+
* set_initial_image() must be called before loading content,
2415+
* i.e. the frontend cannot access image paths in advance
2416+
* and thus cannot perform the error check itself.
2417+
* If set path and content path do not match, the core should
2418+
* ignore the set 'index' value and instead use 0
2419+
* Returns 'false' if index or 'path' are invalid, or core
2420+
* does not support this functionality
2421+
*/
2422+
typedef bool (RETRO_CALLCONV *retro_set_initial_image_t)(unsigned index, const char *path);
2423+
2424+
/* Fetches the path of the specified disk image file.
2425+
* Returns 'false' if index is invalid (index >= get_num_images())
2426+
* or path is otherwise unavailable.
2427+
*/
2428+
typedef bool (RETRO_CALLCONV *retro_get_image_path_t)(unsigned index, char *path, size_t len);
2429+
2430+
/* Fetches a core-provided 'label' for the specified disk
2431+
* image file. In the simplest case this may be a file name
2432+
* (without extension), but for cores with more complex
2433+
* content requirements information may be provided to
2434+
* facilitate user disk swapping - for example, a core
2435+
* running floppy-disk-based content may uniquely label
2436+
* save disks, data disks, level disks, etc. with names
2437+
* corresponding to in-game disk change prompts (so the
2438+
* frontend can provide better user guidance than a 'dumb'
2439+
* disk index value).
2440+
* Returns 'false' if index is invalid (index >= get_num_images())
2441+
* or label is otherwise unavailable.
2442+
*/
2443+
typedef bool (RETRO_CALLCONV *retro_get_image_label_t)(unsigned index, char *label, size_t len);
2444+
23682445
struct retro_disk_control_callback
23692446
{
23702447
retro_set_eject_state_t set_eject_state;
@@ -2378,6 +2455,27 @@ struct retro_disk_control_callback
23782455
retro_add_image_index_t add_image_index;
23792456
};
23802457

2458+
struct retro_disk_control_ext_callback
2459+
{
2460+
retro_set_eject_state_t set_eject_state;
2461+
retro_get_eject_state_t get_eject_state;
2462+
2463+
retro_get_image_index_t get_image_index;
2464+
retro_set_image_index_t set_image_index;
2465+
retro_get_num_images_t get_num_images;
2466+
2467+
retro_replace_image_index_t replace_image_index;
2468+
retro_add_image_index_t add_image_index;
2469+
2470+
/* NOTE: Frontend will only attempt to record/restore
2471+
* last used disk index if both set_initial_image()
2472+
* and get_image_path() are implemented */
2473+
retro_set_initial_image_t set_initial_image; /* Optional - may be NULL */
2474+
2475+
retro_get_image_path_t get_image_path; /* Optional - may be NULL */
2476+
retro_get_image_label_t get_image_label; /* Optional - may be NULL */
2477+
};
2478+
23812479
enum retro_pixel_format
23822480
{
23832481
/* 0RGB1555, native endian.
@@ -2522,8 +2620,20 @@ struct retro_core_option_display
25222620
};
25232621

25242622
/* Maximum number of values permitted for a core option
2525-
* NOTE: This may be increased on a core-by-core basis
2526-
* if required (doing so has no effect on the frontend) */
2623+
* > Note: We have to set a maximum value due the limitations
2624+
* of the C language - i.e. it is not possible to create an
2625+
* array of structs each containing a variable sized array,
2626+
* so the retro_core_option_definition values array must
2627+
* have a fixed size. The size limit of 128 is a balancing
2628+
* act - it needs to be large enough to support all 'sane'
2629+
* core options, but setting it too large may impact low memory
2630+
* platforms. In practise, if a core option has more than
2631+
* 128 values then the implementation is likely flawed.
2632+
* To quote the above API reference:
2633+
* "The number of possible options should be very limited
2634+
* i.e. it should be feasible to cycle through options
2635+
* without a keyboard."
2636+
*/
25272637
#define RETRO_NUM_CORE_OPTION_VALUES_MAX 128
25282638

25292639
struct retro_core_option_value

0 commit comments

Comments
 (0)