Copyright 1993-1994 Apple Computer Inc.  All rights reserved.


Sound Advice (Getting Òsnd Ó resources to the Newt)
version 2

Introduction
Getting sound to the Newton is actually very easy, unfortunately, the current
version of NTK (1.0b4) does not include the build time functions you need to
access sound resources. Luckily that is easy to fix, and here, in easy steps,
is how to fix it...

Working Around the PICT only Resrouces Problem

The current release of NTK only allows automatic access to PICT
resources during the project build. If you want to include other types of
resources, you need to get them manually in your ÒProject DataÓ script.
The basic way to do this is to open the resource file, assign some variable
to the resource then close the resource file. You must also have an evaluate
slot in your project that refers to this variable.

The following example comes from the soundAdvice.¹ project that comes with
this interrim documentation.

Assume you have a file called resources that has a Òsnd Ó resource called
ÒBoingÓ that you want to included in your project. You would go through 5
steps to get this resource:

1.	Create a slot somewhere in you project called mySound, the slot should
be of type evaluate

2.	Bring the project window to the front and choose ÔProject DataÕ from
the Project menu which will bring up a Project Data window.

3.	Type the following into the Project Data window
	rf := OpenResFileX(home & ":resources");
	fredSound := GetSound11("Boing");
	CloseResFileX(rf);
NOTE: "home" is an NTK compile-time variable

4.	Edit the mySound slot and give it a value of fredSound, i.e., the
variable you assigned the sound in your Project Data.

5. Do what you want with that sound.


Opening and Closing Resource Files

The example uses a couple of useful functions for opening and closing
resource files.
	fileId := OpenResFileX(<file-path>)
<file-path> is the full pathname of the file you want to open. 

For example, if your hard drive were called ÒFredÓ, and in fred was a folder
called ÒNewton WorkÓ, with another folder called ÒsrcÓ, then one called
ÒSoundAdviceÓ, and inside that folder was the file called ÒresourcesÓ, the
full path would be:
	ÒFred:Newton Work:src:SoundAdvice:resourcesÓ

Opens the resource file with the full pathname <file-path> and assigns the
file point to the variable fileId. This variable can be used to close the
resource file later.

All resources in this file can be accessed until the file is closed.
	CloseResFileX(fileID)
	fileID is the ID of a file that you get from a call to OpenResFileX
Closes the resource file identifed by the fileID. The resources from that
file are no longer accessible


The Òsnd Ó Resource Functions

Use the new GlobalData file that is part of this information. Just replace
the GlobalData file that comes with NTK. This will give you access to the
sounds functions...
	mySound := GetSound(<sound-name>)
	<sound-name> is the name of a 22Khz sampled  Òsnd Ó resource
This function returns a sound frame based on an Òsnd Ó resource that is
sampled at 22KHz. The sound MUST be sampled at that rate, if not, you will
get an error when you build. The listener will report an error like:

//-- Compiler Error: Sound resource: "Boing" must be sampled at 22 KHz
If you get this error, you probably have a sound that is sampled at 11KHz, so
use the GetSound11 call.
	mySound := GetSound11(<sound-name>)
	<sound-name> is the name of a 11Khz sampled  Òsnd Ó resource
This function returns a sound frame based on an Òsnd Ó resource that is
sampled at 11KHz. The sound MUST be sampled at that rate, if not, you will
get an error when you build. The listener will report an error like:

//-- Compiler Error: Sound resource: "Boing" must be sampled at 11 KHz
If you get this error, you probably have a sound that is sampled at 22KHz, so
use the GetSound call.