mirror/RetroArch
1
0
Fork 0
mirror of https://github.com/libretro/RetroArch synced 2025-04-02 07:20:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #6895 from casdevel/midi

Browse Source 
Document MIDI interface
This commit is contained in:
Twinaphex 2018-06-18 23:53:53 +02:00 committed by GitHub
commit 1feadee0cb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 182 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
libretro-common/include/libretro.h
View File

@ -1177,11 +1177,29 @@ struct retro_led_interface
*/
#define RETRO_ENVIRONMENT_GET_MIDI_INTERFACE (48 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/* struct retro_midi_interface ** --
* Returns a MIDI interface that can be used for raw data I/O.
*/
/* Retrieves the current state of the MIDI input.
* Returns true if it's enabled, false otherwise. */
typedef bool (RETRO_CALLCONV *retro_midi_input_enabled_t)(void);
/* Retrieves the current state of the MIDI output.
* Returns true if it's enabled, false otherwise */
typedef bool (RETRO_CALLCONV *retro_midi_output_enabled_t)(void);
/* Reads next byte from the input stream.
* Returns true if byte is read, false otherwise. */
typedef bool (RETRO_CALLCONV *retro_midi_read_t)(uint8_t *byte);
/* Writes byte to the output stream.
* 'delta_time' is in microseconds and represent time elapsed since previous write.
* Returns true if byte is written, false otherwise. */
typedef bool (RETRO_CALLCONV *retro_midi_write_t)(uint8_t byte, uint32_t delta_time);
/* Flushes previously written data.
* Returns true if successful, false otherwise. */
typedef bool (RETRO_CALLCONV *retro_midi_flush_t)(void);
struct retro_midi_interface

164
midi/midi_driver.h
View File

@ -32,19 +32,172 @@ typedef struct
typedef struct midi_driver
{
/**
* ident:
* Driver name (visible in the menu). Must be unique among the MIDI drivers.
**/
const char *ident;
/**
* get_avail_inputs:
* Populates provided list with currently available inputs (if any).
*
* @inputs : List of available inputs (visible in the menu).
* This argument will never be NULL.
*
* Returns: True if successful (even if there are no inputs available),
* false otherwise.
*
* Remarks: Before this function is called the list will already contain one
* member ("Off") which can be used by the user to disable input.
*
* If the driver supports input but underlying API don't offers this
* list, driver should/must provide some "fake" name(s) here,
* otherwise user will only see "Off" option in the menu.
**/
bool (*get_avail_inputs)(struct string_list *inputs);
/**
* get_avail_outputs:
* Populates provided list with currently available outputs (if any).
*
* @outputs : List of available outputs (visible in the menu).
* This argument will never be NULL.
*
* Returns: True if successful (even if there are no outputs available),
* false otherwise.
*
* Remarks: Before this function is called the list will already contain one
* member ("Off") which can be used by the user to disable output.
*
* If the driver supports output but underlying API don't offers this
* list, driver should/must provide some "fake" name(s) here,
* otherwise user will only see "Off" option in the menu.
**/
bool (*get_avail_outputs)(struct string_list *outputs);
/**
* init:
* Initializes driver and starts input (if 'input' argument is non NULL) and
* starts output (if 'output' argument is non NULL).
*
* @input : One of the input names previously returned by
* the 'get_avail_inputs' function or NULL which
* means don't initialize input.
* @output : One of the output names previously returned by
* the 'get_avail_outputs' function or NULL which
* means don't initialize output.
*
* Returns: Driver specific data pointer if successful, NULL otherwise.
*
* Remarks: If requested input/output is unavailable driver should return
* NULL (don't implement "fallback" mechanism).
**/
void *(*init)(const char *input, const char *output);
/**
* free:
* Stops I/O and releases any resources used by the driver.
*
* @p : Driver specific data pointer previously returned
* by the 'init' function.
* This argument will never be NULL.
**/
void (*free)(void *p);
/**
* set_input:
* This function is used for changing/disabling input.
*
* @p : Driver specific data pointer previously returned
* by the 'init' function.
* This argument will never be NULL.
* @input : One of the input names previously returned by
* the 'get_avail_inputs' function or NULL which
* means disable input.
*
* Returns: True if successful, false otherwise.
*
* Remarks: On error, driver should leave the current input as is (if possible).
**/
bool (*set_input)(void *p, const char *input);
/**
* set_output:
* This function is used for changing/disabling output.
*
* @p : Driver specific data pointer previously returned
* by the 'init' function.
* This argument will never be NULL.
* @output : One of the output names previously returned by
* the 'get_avail_outputs' function or NULL which
* means disable output.
*
* Returns: True if successful, false otherwise.
*
* Remarks: On error, driver should leave the current output as is (if possible).
**/
bool (*set_output)(void *p, const char *output);
/**
* read:
* This function is used for reading received data. When called, 'data_size'
* member of the 'event' argument will hold max data size (in bytes)
* that event can hold. After successful read driver should set this member
* to actual data size that is returned, and 'delta_time' member should be
* set to time (in microseconds) between previous event and this one (if this
* is the first event set 'delta_time' to 0).
*
* @p : Driver specific data pointer previously returned
* by the 'init' function.
* This argument will never be NULL.
* @event : Address of the event structure.
* This argument will never be NULL, 'data' member
* will never be NULL and 'data_size' member
* will never be 0.
*
* Returns: True if event was available and read successfully, false otherwise.
*
* Remarks: If the driver can't supply timing info 'delta_time' member
* of the 'event' argument should be set to 0.
**/
bool (*read)(void *p, midi_event_t *event);
/**
* write:
* This function is used for writing events.
*
* @p : Driver specific data pointer previously returned
* by the 'init' function.
* This argument will never be NULL.
* @event : Address of the event structure.
* This argument will never be NULL, 'data' member
* will never be NULL and 'data_size' member
* will never be 0.
*
* Returns: True if event was written successfully, false otherwise.
*
* Remarks: This event should be buffered by the driver and sent later
* when 'flush' function is called.
*
* If the underlying API don't support event scheduling 'delta_time'
* member of the 'event' argument may be ignored by the driver.
**/
bool (*write)(void *p, const midi_event_t *event);
/**
* flush:
* This function is used for transferring events previously stored by the
* 'write' function.
*
* @p : Driver specific data pointer previously returned
* by the 'init' function.
* This argument will never be NULL.
*
* Returns: True if successful, false otherwise.
*
* Remarks: On error, drivers should keep the events (don't drop them).
**/
bool (*flush)(void *p);
} midi_driver_t;
@ -70,6 +223,17 @@ bool midi_driver_read(uint8_t *byte);
bool midi_driver_write(uint8_t byte, uint32_t delta_time);
bool midi_driver_flush(void);
/**
* midi_driver_get_event_size:
* This is a convenience function for finding out the size of the event based
* on the status byte.
*
* @status : Status (first) byte of the event.
*
* Returns: Size of the event (in bytes). If 'status' argument is invalid
* (< 0x80) or 'status' represents start of the "SysEx" event (0xF0)
* this function will return 0.
**/
size_t midi_driver_get_event_size(uint8_t status);
RETRO_END_DECLS