@database "SoundDT v39.30 Guide"
@copyright "Copyright ©1996 by Jonathan Gapen"

@node main "SoundDT v39.30 Documentation"


------------------------------------------------------------------------------
                                @{fg shine}SoundDT v39.30@{fg text}
               A replacement soundclass for the DataTypes system.

           Copyright ©1996 by Jonathan Gapen (innuendo@execpc.com)
                           @{" Some rights reserved. " link Legal }
------------------------------------------------------------------------------

   @{ " · " link Intro     } Introduction                    Why a soundclass replacement?
   @{ " · " link Install   } Installation & Use              Installing and using the software.
   @{ " · " link Legal     } Legal Issues                    License, distribution, disclaimer.
   @{ " · " link Credits   } Credits                         Thanks and credit where credit is due.
   @{ " · " link Problems  } Problems                        Known bugs/problems
   @{ " · " link History   } History                         History of changes.
   @{ " · " link Future    } Future                          Plans for future versions.
    
@endnode

@node Intro "SoundDT v39.30 - Introduction"

@{fg shine}Why a new DataTypes soundclass?@{fg text}
-------------------------------

Short answer: sunau.datatype
Long answer:
     The DataTypes soundclass provided with AmigaOS 3.0 has a few annoying
limitations. Foremost, it does not support double-buffering, and cannot play
sounds longer than the hardware limit of 128 kilobytes. Secondly, it must load
all sample data into chip RAM, of which a modern Amiga has only 2 megabytes.
Loading the sample into fast RAM, of which a modern Amiga may have over a
gigabyte, makes more room available for sample data. Last, the button image (a
little speaker icon) lacks style and visual impact.
     In addition, the Commodore sunau.datatype assumes that it runs under
AmigaOS 3.1, and loads sample data into fast RAM, when possible. Users of
AmigaOS 3.0 hear only static, when that happens.
     My sound.datatype v39.30 fixes these annoying little problems.

@endnode

@node Install "SoundDT v39.30 - Installation & Use"

@{fg shine}Installation@{fg text}
------------

     To install this new DataTypes class, copy the file sound.datatype from the
archive to SYS:Classes/DataTypes, either with the CLI, or your favorite
directory tool. That's it.
     You may wish to retain a backup copy of the original sound.datatype, in
case any problems appear. Simply copy SYS:Classes/DataTypes/sound.datatype to a
safe place.

@{fg shine}Use@{fg text}
---

     Use this version exactly as you would use the original Commodore version.

@endnode

@node Legal "License, Distribution, Disclaimer"

@{fg shine}License@{fg text}
-------

     Under this license, you are granted use of the sound.datatype v39.30 ('the
software') for any purpose, free of charge. Installation and use of the software
implies your acceptance of the terms of this license.

@{fg shine}Distribution@{fg text}
------------

     This software is freely distributable in the form of the compressed archive
released by Jonathan Gapen, and in this form only. You may not add or remove any
files, but you may convert the archive into another format. All methods of
distribution are allowed. However, no fees for the distribution of this software
may be charged, beyond the cost of media and compilation.

@{fg shine}Disclaimer@{fg text}
----------

     NO WARRANTY AS TO THE PERFORMANCE, COMPATIBILITY, OR FITNESS FOR ANY
PARTICULAR PURPOSE IS MADE. NO TECHNICAL SUPPORT IS GUARANTEED. ALL USE OF THE
SOFTWARE IS AT THE USER'S OWN RISK.

   The sound.datatype v39.30 is Copyright ©1996 by Jonathan Gapen.

@endnode

@node Credits "SoundDT v39.30 - Credits"

Special thanks are due:

   · Stefan Ruppert, for including source code with his binary.datatype, which
   gave the best example of exactly how to create the shared library, confirmed
   my suspicions on how to write a superclass, and saved me from a number of 
   stupid mistakes.

   · Olaf Barthel, for including source in his aiff.datatype, which shows how
   sound subclasses allocate sample memory, and further clarification of some
   finer points of library creation.

   · Randall Jesup and David Junod, for the DataTypes system.

   · Amiga Technologies GmbH and VIScorp, for trying to continue the Amiga
   tradition in the face of many obstacles.

No thanks to:

   · Commodore International Limited

@endnode

@node Problems "SoundDT v39.30 - Known Bugs"

     A number of people have used this software for quite some time, and I've
received one bug report, which I believe was caused by other software. However,
it has some non-fatal problems, but nothing too serious.

   · @{fg shine}Long sounds won't abort!@{fg text}

     Unfortunately, my audio player routine is not smart enough to abort
double-buffered sounds. I made it very logical to eliminate the possibility of
subtle bugs, but the structure of the code makes it very difficult to cleanly
abort double-buffered sounds. I like it better this way, rather than the way the
original sound.datatype chopped them off at random points, though! :-)

   · @{fg shine}The gadget image doesn't like Multiview with SysIHack!@{fg text}

     Actually, Multiview itself doesn't like SysIHack; it assumes a fixed size
for the system scrollbars. Therefore, it reports the wrong values for the inner
dimensions of the window to the DataTypes object. I can't fix it without a bad
hack, and it's only a cosmetic bug, so I leave it alone.
     If it really bothers you, please feel free to write a new Multiview.

@endnode

@node History "SoundDT v39.30 - History of Changes"

v39.30
   · First public release.

@endnode

@node Future "SoundDT v39.30 - Future"

I have a few plans for future features. Take a look:

   · @{fg shine}AHI Support@{fg text}

     Especially if somebody would kindly write a better example of double-
buffering with AHI. I find the one in the archive virtually impossible to
decipher.

   · @{fg shine}Aborting Double-Buffered Sounds@{fg text}

     It will require a re-think of my player routine, but other programs do it,
so how hard can it be?
     
   · @{fg shine}Bigger! Better! More! @{fg text}

     I have defined a new compatible API for multi-channel sounds of up to
32-bit resolution, and even implemented it. Now I need to write good player
routines for AHI and the Paula chip.

@endnode