diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api-asm.68k | 30 | ||||
| -rw-r--r-- | doc/api-c.txt | 18 | ||||
| -rw-r--r-- | doc/esf.txt | 21 |
3 files changed, 60 insertions, 9 deletions
diff --git a/doc/api-asm.68k b/doc/api-asm.68k index 8c0995c..3293b9e 100644 --- a/doc/api-asm.68k +++ b/doc/api-asm.68k @@ -20,6 +20,7 @@ Unless stated otherwise, calling the API subroutines will *not* modify the *** Initialization *** Echo_Init + in a0 = pointer to instrument list Initializes Echo. Loads the instrument list, loads the Z80 engine and gets it running. You need to call this before you can use Echo (usually when @@ -42,20 +43,29 @@ Echo_Init *** Background music *** Echo_PlayBGM + in a0 = pointer to ESF data to play Starts playback of the specified background music. The register a0 points to the ESF data for the background music. 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). + Stops playback of background music. Used both to stop and to pause music. + +Echo_PauseBGM + + Pauses BGM playback (SFXs should be unaffected). + +Echo_ResumeBGM + + Resumes BGM playback after it has been paused with Echo_PauseBGM. ============================================================================= *** Sound effects *** Echo_PlaySFX + in a0 = pointer to ESF data to play Starts playback of the specified sound effect. The register a0 points to the ESF data for the sound effect. @@ -69,6 +79,7 @@ Echo_StopSFX *** Direct events *** Echo_PlayDirect + in a0 = pointer to ESF data to inject Injects events to be played as part of the BGM the next tick. The register a0 points to the ESF data to be injected. @@ -91,6 +102,7 @@ Echo_PlayDirect *** Control *** Echo_GetStatus + out d0 = status (see below) Gets the current status of Echo. The status is returned as a word in d0, with the following bits set as relevant: @@ -105,6 +117,7 @@ Echo_GetStatus the 68000 until Echo is ready to take more commands. Echo_SetVolume + in d0 = new volume ($00 = quietest, $FF = loudest) Sets the global volume. Register d0 is a byte value ranging from 0 (quietest) to 255 (loudest), and every channel is affected immediately. @@ -114,20 +127,26 @@ Echo_SetVolume on the volume value (the cut off point is at 25%). Echo_SetVolumeEx + in a0 = pointer to volume data (see below) 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 + a list of 16 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). + + NOTE: the Echo 1.4 docs requested for 13 bytes instead of 16. This has + been changed for the sake of expansion. Currently the extra bytes are + ignored, but consider adapting your code (just set them to zero). ============================================================================= *** Settings *** Echo_SetPCMRate + in d0 = new PCM rate (see below) Changes the sample rate of PCM. Note this is a global parameter as it affects both BGM and SFX. The value is what one would write in timer A of @@ -153,17 +172,22 @@ Echo_SetPCMRate *** Raw access *** Echo_SendCommand + in d0 = command Sends an argument-less command to Echo. The command ID is given as a byte in register d0. Echo_SendCommandAddr + in d0 = command + in a0 = address Sends a command to Echo that takes an address as its argument. The command ID is given as a byte in register d0, while the address argument is given in register a0. Echo_SendCommandByte + in d0 = command + in d1 = argument Sends a command to Echo that takes a byte as its argument. The command ID is given as a byte in register d0, while the byte argument is given in diff --git a/doc/api-c.txt b/doc/api-c.txt index 24c6312..541a895 100644 --- a/doc/api-c.txt +++ b/doc/api-c.txt @@ -52,8 +52,15 @@ void echo_play_bgm(const void *esf) 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). + Stops playback of background music. Used both to stop and to pause music. + +void echo_pause_bgm() + + Pauses BGM playback (SFXs should be unaffected). + +void echo_resume_bgm() + + Resumes BGM playback after it has been paused with echo_pause_bgm. ============================================================================= @@ -120,12 +127,16 @@ void echo_set_volume(uint8_t vol) 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 + points to a list of 16 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). + + NOTE: the Echo 1.4 docs requested for 13 bytes instead of 16. This has + been changed for the sake of expansion. Currently the extra bytes are + ignored, but consider adapting your code (just set them to zero). ============================================================================= @@ -162,6 +173,7 @@ void echo_send_command(uint8_t command) command to send, and may be one of the following: ECHO_CMD_STOPBGM ..... Stop background music playback + ECHO_CMD_PAUSEBGM .... Pause background music playback ECHO_CMD_RESUMEBGM ... Resume background music playback ECHO_CMD_STOPSFX ..... Stop sound effect playback diff --git a/doc/esf.txt b/doc/esf.txt index a96e35d..eb04474 100644 --- a/doc/esf.txt +++ b/doc/esf.txt @@ -367,12 +367,27 @@ $F9rrnn: Set FM register in bank 1 ============================================================================= -$FC: Go to loop [BGM ONLY] -$FD: Set loop point [BGM ONLY] +$FAnn: Set flags - This event are used in BGM streams to loop music. Put event $FD where the + This event will set some of the flags. The value nn is a bitmask that is + OR'd with the current flags. + +$FBnn: Clear flags + + This event will clear some of the flags. The value nn is a bitmask that + is AND'd with the current flags. + +============================================================================= + +$FC: Go to loop +$FD: Set loop point + + This event are used in streams to loop music. Put event $FD where the loop starts, and then end the stream using event $FC (don't use event $FF). This will tell Echo to loop the song instead of stopping playback. + + SFX support for this event was added in 1.5, if you loop a sound effect + you'll have to either stop it manually or play another SFX. $FEnn: Delay ticks |