THE DIGITAL RENDERER MODULE, V0.21
==================================



This module provides a polling- or call-back interface between applications and
the sound system. It should be used if you wish to playback a sample of unknown
length like when emulating another computer's sound system and/or control playback
from applications which might be mapped out during WIMP polls. Otherwise you
better use voice generators.

You tell it the number of channels, sample period and buffer size (as needed for
SWI Sound_Configure) when activating it. The module will then claim a buffer of
the specified size (unless you want a call-back interface in which case no buffer
will be needed) and take over the sound system. Your job as a client is either
polling with DigitalRenderer_ReadState and providing new samples when needed
using DigitalRenderer_NewSample (polling method) or providing a buffer fill code
that'll be called by the module when the sample buffer has to be filled.

DigitalRenderer only supports 8 bit logarithmic sound ATM since I have absolutely
no documentation about 16 bit linear sound (and the PRMs are pretty useless as
far as DMA- and Channel-Handlers are concerned). If any of you provided me with
the necessary docs I might update it.




The DigitalRenderer uses SWI chunk &4f700 (officially registered). It provides
the following SWI calls:







DigitalRenderer_Activate		SWI &4F700
========================


On Entry:
---------

R0	bits 0-7: number of channels, will get rounded up to (1,2,4,8).
	bit 31: clear ==> use polling, otherwise call back buffer fill code.
R1	Sample length (bytes per channel, must be a multiple of 16 bytes)
R2	Sample period (microseconds between reading two consecutive sample bytes)
R3	pointer to buffer fill code if R0 bit 31 set.


On Exit:
--------

---


Usage:
------

Your application must call this SWI to take over the sound system. For typical
values of sample length and sample period see PRM 4. Once (successfully)
activated things like the system beep won't work any more.


Buffer Fill Code:
-----------------

The buffer fill code has the following entry/exit conditions:

On Entry:
---------
R0	*buffer (in DMA space)
R1	*LinToLog (8kB lookup table)
R2	buffer length

Processor is in IRQ mode with IRQs enabled. Therefore do not use r14_irq under
any circumstances!

On Exit:
--------
Except for r13_irq no registers have to be preserved. The routine must
return using "LDMIA sp!,{pc}" (the return address is pushed to the stack
_before_ the routine is called).


The buffer fill code has to fill the buffer in the format the VIDC needs, i.e.
all channels interleaved, each channel in 8bit u-law.

	

Errors:
-------

	- already active
	- can't claim memory for buffer / handler
	- bad buffer size (not a multiple of 16)





DigitalRenderer_Deactivate		SWI &4F701
==========================


On Entry:
---------

---


On Exit:
--------

---


Usage:
------

If your application doesn't need sound any more it must return control to the
old handlers by issuing this SWI.


Errors:
-------

	- not active





DigitalRenderer_Pause			SWI &4F702
=====================


On Entry:
---------

---


On Exit:
--------

---


Usage:
------

This SWI suspends sound playback (disabling DMA on sample buffers and so on).
In contrast to deactivating DR this will not install the old handlers but merely
mute the entire sound system.


Errors:
-------

	- not active





DigitalRenderer_Resume			SWI &4F703
======================


On Entry:
---------

---


On Exit:
--------

---


Usage:
------

Call this to resume playback after it was paused.


Errors:
-------

	- not active





DigitalRenderer_GetTables		SWI &4F704
=========================


On Entry:
---------

---


On Exit:
--------

R0	pointer to 8k LinToLog table for translating 13 bit signed integers
	to 8 bit logarithmic samples as required by the VIDC, scaled to the
	currently selected volume (--> SWI Sound_Volume)

R1	Pointer to 256 byte LogScale table for scaling 8 bit logarithmic
	samples according to the currently selected volume.


Errors:
-------

	- not active





DigitalRenderer_ReadState		SWI &4F705
=========================


On Entry:
---------

---


On Exit:
--------

R0	Digital Renderer State. Bits and their meaning when set:

	0:	DigitalRenderer active
	1:	New sample data required
	2:	Buffer overflow occurred


Usage:
------

Call this SWI to poll DigitalRenderer. If Bit 1 is set you have to provide a
new sample buffer by calling DigitalRenderer_NewSample. Bit 2 lets you check
for buffer overflows (i.e. your application took too long to provide the next
sample).
If you're using the call-back method only bit 0 has any meaning.






DigitalRenderer_NewSample		SWI &4F706
=========================


On Entry:
---------

R0	Pointer to buffer holding new samples (8bit ulaw)


On Exit:
--------

---


Usage:
------

Don't call this SWI if you're using the call-back method, this is for polling only.
Call this when DigitalRenderer_ReadState returned with Bit 1 set. The buffer must
have the correct size (number of channels * Sample length) and contain data that
can be sent directly to the VIDC, i.e. 8 bit logarithmic data, interleafed for
multiple channels.


Errors:
-------

	- not active





DigitalRenderer_New16BitSample		SWI &4F707
==============================

On Entry:
---------

R0	Pointer to buffer holding new samples (16bit linear)

On Exit:
--------

---


Usage:
------

Same as DigitalRenderer_NewSample, but the source buffer holds 16bit linear samples
(and hence has to be twice the size of the one used by DigitalRenderer_NewSample).






DigitalRenderer_BufferStatistics	SWI &4F708
================================

On Entry:
---------

---

On Exit:
--------

R0	Buffers played
R1	Buffers provided by application


Usage:
------

A simple method to get statistical information about the playback history. Both
counters will be reset to zero when the DigitalRenderer is activated.








LEGAL STUFF:
============


The DigitalRenderer module is Freeware. You may use it for your own programs as
long as this file is included unchanged. I won't be held responsible for any kind
of damage resulting from the use of this module, use it entirely at your own risk.





CONTACT:
========


Andreas Dehmel
Am Schorn 18
82327 Tutzing
Germany

email:	dehmel@forwiss.tu-muenchen.de
