The Complete Animator

Software for your Enjoyment, Creativity, Productivity and Education

Iota Software Ltd - The IotaSound module - SWIs

The IotaSound module - SWIs

This page documents the SWI interface provided by the IotaSound module, as of version 0.12. All obey the standard SWI conventions: registers not mentioned in the descriptions below can be assumed to be preserved; errors are reported by setting the V bit and returning an error pointer in R0; none of these SWIs are re-entrant and none can be called from interrupt routines.

Many of these SWIs can be regarded as for internal use only by The Complete Animator and the IotaSound module itself. They're documented here basically because nothing winds me up more than a useful-looking module inside a commercial application, with no information on how to use it!

Contents

IotaSound_ADPCMtoVIDC (SWI &81ECC)

On entry: 
    R0 = pointer to destination buffer
    R1 = pointer to source buffer
    R2 = number of samples to convert
This call uncompresses an ADPCM sample and converts it into (ordinary) VIDC format. The buffer at R0 must be at least R2 bytes long. Ceil(R2/2) bytes are read from the buffer at R1.

It is mainly for internal use -- if you use IotaSound_LoadTable or IotaSound_LoadFile to load a table containing ADPCM samples, they will be expanded automatically when IotaSound copies them into its own workspace.

The code for this call is based on C code by Stichting Mathematisch Centrum.

IotaSound_Allocate (SWI &81EC6)

On entry: 
    R0 = wave table handle (see overview)
    R1 = signed amount of memory to add (bytes)
 (or)
    R0 = 0 to allocate a new wave table
    R1 = amount of memory required
On exit: 
    R0 = wave table handle (won't have changed
              unless 0 was passed in)
    R1 = table size
    R2 = current table base address

This call either allocates a new table (in which case you must eventually call IotaSound_ReleaseTable on it) or changes the size of an existing wave table.

This is quite dangerous if you don't know what you're doing, and in fact this SWI is best regarded as being for The Complete Animator's internal use only. If you are writing an application which generates wave tables, the recommended course of action is to keep the table in your application space as a SoundLib file and keep going ReleaseTable/LoadFile whenever it changes.

Don't worry, this policy doesn't lead to fragmentation - IotaSound keeps its workspace compacted at all times.

IotaSound_DeregisterApp (SWI &81EC2)

No parameters, preserves all.

Call this when your application exits. If yours was the last application using IotaSound, the sound system will be released. You can use
*help iotasound
to show you how many applications are registered.

See also: IotaSound_RegisterApp

IotaSound_InitSystem (SWI &81EC0)

On entry: 
    R0 = 0..8 to set the number of sound voices
         -1   to read the number of sound voices
On exit: 
    R0 = number of voices currently active

This call sets the number of active sound voices, and has just the same effect as BBC BASIC's VOICES command.

The rather grandiose and misleading name is a legacy of very early versions of the IotaSound module in which it was necessary to call this SWI at the beginning of your application to start things up. This is no longer the case and you shouldn't need to use this SWI unless you really want to read or change the number of active voices (and you aren't writing in BASIC).

IotaSound_LoadFile (SWI &81ECB)

On entry: 
    R0 points to pathname of SoundLib file
On exit: 
    R0 = wave table handle (see overview)
    R1 = number of sounds in the file

For each file you load with LoadFile, you must eventually call IotaSound_ReleaseTable to free the memory.

IotaSound_LoadTable (SWI &81EC3)

On entry: 
    R0 points to a Film file in memory
    R1 = length of the file pointed to by R0
On exit: 
    R0 = wave table handle (see overview)
For each file you load with LoadTable, you must eventually call IotaSound_ReleaseTable to free the memory.

IotaSound_Play (SWI &81EC5)

On entry: 
    R0 = wave table handle
    R1 points to sound block
On exit: 
    R0 preserved
    R1 points to the byte after the sound block
    R2,R3 corrupted

This routine plays one or more sounds from a given wave table. (If you just want to use the default pitch, duration and volume, you can use the simpler call IotaSound_TrySound.)

IotaSound_PlayIndirected (SWI &81EC9)

On entry: 
    R0 = wave table handle
    R1 points to sound block
    R2 and R3 each point to an array of 8-byte structures
On exit: 
    R0 preserved
    R1 points to the byte after the sound block
    R2,R3 preserved

This call is very much like IotaSound_Play, except that the sample numbers in the sound blocks are looked up in two indirection tables first.

IotaSound_Playing (SWI &81ECA)

On exit: 
    R0 = 0 if no sounds are currently playing
              else non-zero
    R1 corrupted

IotaSound_RegisterApp (SWI &81EC1)

No parameters, preserves all.

Call this to register your application with the IotaSound module. When your application exits, call IotaSound_DeregisterApp.

IotaSound_ReleaseTable (SWI &81EC4)

On entry: 
    R0 = wave table handle

You must call this when you've finished with each wave table created by IotaSound_LoadTable, IotaSound_LoadFile, or IotaSound_Allocate. It de-allocates all the memory associated with that wave table.

IotaSound_Stop (SWI &81EC8)

No parameters, preserves all.

This call stops dead all sounds which are currently playing.

In fact, it sets a flag so that all the voice generators stop dead at the end of their next buffer fill, and then waits until they've all done so. In other words, once Stop has returned, the voice generators are guaranteed not to touch the wave table again and you can release it straightaway.

IotaSound_TrySound (SWI &81EC7)

On entry: 
    R0 = wave table handle
    R1 = sample number
On exit: 
    R0,R1 preserved
    R2,R3 corrupted

This routine plays one sample from a given wave table. See the example code.

IotaSound_VIDCtoADPCM (SWI &81ECD)

On entry: 
    R0 points to destination buffer
    R1 points to source buffer
    R2 = number of samples

This call compresses an 8 bit VIDC sample (the usual sort on Acorn machines) using ADPCM compression.

At least R2/2 bytes must be available in the buffer pointed to by R0.

The code used in this call is based on code by Stichting Mathematisch Centrum.

Glossary

ADPCM
Adaptive Differential Pulse Code Modulation: a simple (and thus extremely cunning) method of compressing 16-bit linear digital audio signals into 4 bits per sample. The IotaSound module uses ADPCM after first converting its 8-bit logarithmic data into 16-bit linear using a lookup table. The compression isn't lossless, and relies on "fooling the ear" in the same way that JPEG compression of images "fools the eye": information is removed, but only information that can't really be detected anyway.


Home Page
Top of page