diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api-asm.68k | 47 | ||||
| -rw-r--r-- | doc/api-c.txt | 53 | ||||
| -rw-r--r-- | doc/esf.txt | 43 |
3 files changed, 129 insertions, 14 deletions
diff --git a/doc/api-asm.68k b/doc/api-asm.68k index b6fa48b..8c0995c 100644 --- a/doc/api-asm.68k +++ b/doc/api-asm.68k @@ -51,11 +51,6 @@ Echo_StopBGM Stops playback of background music. Used both to stop and to pause music (the latter can be undone with Echo_ResumeBGM, see below). -Echo_ResumeBGM - - Resumes playback of whatever background music was playing last time before - Echo_StopBGM was called. Used when you want to unpause music. - ============================================================================= *** Sound effects *** @@ -71,6 +66,28 @@ Echo_StopSFX ============================================================================= +*** Direct events *** + +Echo_PlayDirect + + Injects events to be played as part of the BGM the next tick. The register + a0 points to the ESF data to be injected. + + The injected events are a small stream on their own. The last event must + be $FF (this will return back to the BGM). Do *not* issue $FC, $FD or $FE + events, as you'll just break everything instead. + + The buffer is small, so don't go overboard. There's room for up to 128 + bytes (though again, each event is just 2-3 bytes). If there were direct + events pending to play, the new events will be appended at the end, so + take this into account when it comes to the buffer usage. You can check + if there are pending events with Echo_GetStatus (see bit 14) if you're + worried about running out of space. + + The buffer is only checked every tick. + +============================================================================= + *** Control *** Echo_GetStatus @@ -80,12 +97,32 @@ Echo_GetStatus Bit 0 .... Sound effect is playing Bit 1 .... Background music is playing + Bit 14 ... Echo isn't done parsing direct events Bit 15 ... Echo is busy (can't take commands) The API will automatically wait if you try to send a command while Echo is busy, so the only reason to check for that is if you don't want to halt the 68000 until Echo is ready to take more commands. +Echo_SetVolume + + Sets the global volume. Register d0 is a byte value ranging from 0 + (quietest) to 255 (loudest), and every channel is affected immediately. + The scale of the volume in this case is *linear*. + + Note that since PCM doesn't have volume, it gets toggled on/off depending + on the volume value (the cut off point is at 25%). + +Echo_SetVolumeEx + + Sets the global volume for each channel separately. Register a0 points to + a list of 13 bytes (one for each Echo channel). Values for FM and PSG + channels are given in the same way as in events, that is: logarithmic + scale, 0..127 for FM, 0..15 for PSG, lower = louder. + + The last byte (the one belonging to the PCM channel) is used to toggle + whether PCM plays, either 0 (disabled) or 1 (enabled). + ============================================================================= *** Settings *** diff --git a/doc/api-c.txt b/doc/api-c.txt index f0dd326..24c6312 100644 --- a/doc/api-c.txt +++ b/doc/api-c.txt @@ -55,11 +55,6 @@ void echo_stop_bgm() Stops playback of background music. Used both to stop and to pause music (the latter can be undone with echo_resume_bgm, see below). -void echo_resume_bgm() - - Resumes playback of whatever background music was playing last time before - echo_stop_bgm was called. Used when you want to unpause music. - ============================================================================= *** Sound effects *** @@ -75,6 +70,28 @@ void echo_stop_sfx() ============================================================================= +*** Direct events *** + +void echo_play_direct(const void *esf) + + Injects events to be played as part of the BGM the next tick. The + parameter 'esf' points to the ESF data to be injected. + + The injected events are a small stream on their own. The last event must + be $FF (this will return back to the BGM). Do *not* issue $FC, $FD or $FE + events, as you'll just break everything instead. + + The buffer is small, so don't go overboard. There's room for up to 128 + bytes (though again, each event is just 2-3 bytes). If there were direct + events pending to play, the new events will be appended at the end, so + take this into account when it comes to the buffer usage. You can check + if there are pending events with Echo_GetStatus (see ECHO_STAT_DIRBUSY) + if you're worried about running out of space. + + The buffer is only checked every tick. + +============================================================================= + *** Control *** uint16_t echo_get_status() @@ -82,14 +99,34 @@ uint16_t echo_get_status() Gets the current status of Echo. Returns an OR of the following flags, as relevant: - ECHO_STAT_BGM .... Background music is playing - ECHO_STAT_SFX .... Sound effect is playing - ECHO_STAT_BUSY ... Echo is busy (can't take commands) + ECHO_STAT_BGM ....... Background music is playing + ECHO_STAT_SFX ....... Sound effect is playing + ECHO_STAT_DIRBUSY ... Echo isn't done parsing direct events + ECHO_STAT_BUSY ...... Echo is busy (can't take commands) The API will automatically wait if you try to send a command while Echo is busy, so the only reason to check for that is if you don't want to halt the 68000 until Echo is ready to take more commands. +void echo_set_volume(uint8_t vol) + + Sets the global volume. The value 'vol' ranges from 0 (quietest) to 255 + (loudest), and every channel is affected immediately. The scale of the + volume in this case is *linear*. + + Note that since PCM doesn't have volume, it gets toggled on/off depending + on the volume value (the cut off point is at 25%). + +void echo_set_volume_ex(const uint8_t *ptr) + + Sets the global volume for each channel separately. The parameter 'ptr' + points to a list of 13 bytes (one for each Echo channel). Values for FM + and PSG channels are given in the same way as in events, that is: + logarithmic scale, 0..127 for FM, 0..15 for PSG, lower = louder. + + The last byte (the one belonging to the PCM channel) is used to toggle + whether PCM plays, either 0 (disabled) or 1 (enabled). + ============================================================================= *** Settings *** diff --git a/doc/esf.txt b/doc/esf.txt index a7b833e..a96e35d 100644 --- a/doc/esf.txt +++ b/doc/esf.txt @@ -85,6 +85,8 @@ EVENT LIST $4Ann ..... Set instrument PSG channel #3 $4Bnn ..... Set instrument PSG channel #4 + $Dn ....... Delay ticks (short) + $E0 ....... [SFX] Lock FM channel #1 $E1 ....... [SFX] Lock FM channel #2 $E2 ....... [SFX] Lock FM channel #3 @@ -103,9 +105,12 @@ EVENT LIST $F5nn ..... Set parameters FM channel #5 $F6nn ..... Set parameters FM channel #6 + $F8rrnn ... Set FM register in bank 0 + $F9rrnn ... Set FM register in bank 1 + $FC ....... [BGM] Go to loop $FD ....... [BGM] Set loop point - $FEnn ..... Delay ticks + $FEnn ..... Delay ticks (long) $FF ....... Stop playback ============================================================================= @@ -288,6 +293,14 @@ $4Bnn: Set instrument PSG channel #4 ============================================================================= +$D0~$DF: Delay ticks (short) + + Same as $FE01 to $FE10 ($D0 = $FE01, $D1 = $FE02, etc.). Just a shorter + variant of the event to reduce space usage for shorter delays (which are + the most common). + +============================================================================= + $E0: Lock FM channel #1 [SFX ONLY] $E1: Lock FM channel #2 [SFX ONLY] $E2: Lock FM channel #3 [SFX ONLY] @@ -326,6 +339,34 @@ $F6: Set parameters FM channel #6 ============================================================================= +$F8rrnn: Set FM register in bank 0 +$F9rrnn: Set FM register in bank 1 + + These events are used to change the value of a YM2612 register directly. + The rr byte indicates the register, the nn byte is the value to be + written into it ($F8 writes to $4000/1, $F9 writes to $4002/3). + + HERE BE DRAGONS, USE AT YOUR OWN RISK. The channel locking mechanism will + *not* take care of this event, and if a SFX locks the channel then the + register will *not* be restored properly once the SFX is over. + + More specifically: + + * If you use it on a BGM, don't let it touch any channels that may + get locked by SFXs. + + * If you use it on a SFX for an effect on the SFX itself, use it only + for channels locked by that SFX. + + * If you use it on a SFX to affect the music, use it only on channels + that are *not* locked by any SFX (same as first rule, actually). + + * It's possible to touch the global registers ($22~$2B in bank 0). + Do it at your own risk. You may mess up with Echo's functionality, + so be careful about it and make sure you know what you're doing. + +============================================================================= + $FC: Go to loop [BGM ONLY] $FD: Set loop point [BGM ONLY] |