From b4c4cefb706f9c43a54fecb18cb8ee50f0f0e19a Mon Sep 17 00:00:00 2001 From: Chris Xiong Date: Mon, 11 Nov 2019 23:38:09 +0800 Subject: New UI hook "main.seek". Fix SysExc. message sending. API documentation update. Simple visualization no longer have notes stuck after seeking. System exclusive messages longer than 256 bytes are now sent correctly. --- doc/APIdoc.md | 22 +++++++--------------- 1 file changed, 7 insertions(+), 15 deletions(-) (limited to 'doc') diff --git a/doc/APIdoc.md b/doc/APIdoc.md index 8e3a181..ec1eccb 100644 --- a/doc/APIdoc.md +++ b/doc/APIdoc.md @@ -51,7 +51,7 @@ Your plugin is expected to register handlers (hooks) and functionalities when `i and do clean-up jobs when `deinit()` is caled. Aside from the generic functionalities that you can add by implementing the class `qmpFuncBaseIntf`, -You can add these features to QMidiPlayer by implementing their corresponding classes: +You can also add these features to QMidiPlayer by implementing their corresponding classes: - MIDI File Reader (`qmpFileReader`) - MIDI Out Device (`qmpMidiOutDevice`) @@ -60,21 +60,22 @@ You can add these features to QMidiPlayer by implementing their corresponding cl - Event reader, after an event is read or after the whole file reading process is completed (via `(un)registerEventReaderIntf` and `(un)registerFileReadFinishedHandlerIntf`) -- Event handler, when an event is going to be sent by the player (via `(un)registerEventHandlerIntf`) +- Event handler, when an event is going to be sent (or already sent) by the player (via `(un)registerEventHandlerIntf`) - File read finished, when the entire file has been read. (via `(un)registerFileReadFinishedHandlerIntf`) - UIHooks, which are triggered by UI events. (via `(un)registerUIHook`) The first argument defines which event shall trigger the callback. All valid events are listed below: - * `main.stop`: stop button clicked, or playback stopped because end of track reached, or (oddly) switching tracks. + * `main.stop`: stop button clicked, or playback stopped because end of track reached, or (oddly) switching tracks. * `main.start`: track started playing (includes resuming from pause and switching tracks). * `main.pause`: playback paused * `main.reset`: (odd enough) when loading a new file + * `main.seek`: seeking happened Hooks use the universal `ICallBack` interface. Some of those also accept a pointer to a function (`callback_t`). When you register a hook, you provide the core with a instance of your class that implements the `ICallBack` interface and your `userdata` to be used when the core is calling the callback. When the callback is called, it will be fed with proper `callerdata` generated by the core and the `userdata` you provided. Type of `callerdata` varies by hooks. Event -reader and handler hooks have `SEventCallBackData*` as their `callerdata`. All other callbacks at this time have `nullptr` +reader and handler hooks have `SEvent*` as their `callerdata`. All other callbacks at this time have `nullptr` as their `callerdata`. **Don't try directly modifying the members of callerdata!** # 4. Functionalities @@ -128,8 +129,7 @@ yourself in the `deinit()` function of your plugin. 3. Do not throw exceptions to the core. The core doesn't handle exceptions and they will crash the entire program. Use the return value to indicate failure of a procedure instead. 4. The core does not handle MIDI running status, nor does it send events to any component with running status either. -That is to say, the `type` parameter found in `SEvent` and `SEventCallBackData` should always be greater than or equal to -0x80. +That is to say, the `type` parameter found in `SEvent` should always be greater than or equal to 0x80. # 7. Reference @@ -157,14 +157,6 @@ fills the event with the parameters given. - `friend bool operator <(const SEvent& a,const SEvent& b)` compares events by their timestamps. Ties are broken by comparing precedence in file. -### struct `SEventCallBackData` -A stripped down version of SEvent that is used to pass event data in APIs. - -- `uint32_t time` -- `uint32_t type` -- `uint32_t p1` -- `uint32_t p2` - ### class `CMidiTrack` Describes a single MIDI track. A MIDI track consists of multiple MIDI events. The order of events in `eventList` does not matter as long as the timestamps are correct. @@ -268,7 +260,7 @@ Deinitializes the device. - `virtual void basicMessage(uint8_t type,uint8_t p1,uint8_t p2)=0` Sends a basic midi message. Note that the core doesn't make use of running status. -- `virtual void extendedMessage(uint8_t length,const char* data)=0` +- `virtual void extendedMessage(uint32_t length,const char* data)=0` Sends an extended message. ("system exclusive message"). - `virtual void rpnMessage(uint8_t ch,uint16_t type,uint16_t val)=0` Sends a registered parameter number controller message. -- cgit v1.2.3