[id] = CreateSample(id, table, pitch[, fmt, length])
id
,
CreateSample()
will automatically select an identifier and return
it to you. You also have to specify the desired playback frequency for
this sample in the pitch argument. The optional argument fmt
allows you
to specify the format of the PCM data you are about to pass to this
function. Currently, the following formats are supported: #MONO8
(which is the default), #STEREO8
, #MONO16
, and #STEREO16
. The optional
argument length
specifies the desired length in PCM frames for the
new samples.
The sample data must be passed as signed integers. For 8-bit samples the valid sample range runs from -128 to 127, and for 16-bit samples the valid sample range runs from -32768 to 32767.
If you want to create a stereo sample, you must pass interleaved PCM data, i.e. left channel sample is followed by right channel sample is followed by left channel sample, and so on.
Starting with Hollywood 5.0, the PCM data can be passed to this function
in a number of different ways. CreateSample()
can use an array of PCM samples,
an identifier of an open file, or a memory block as the source for the
new sample. Which source is used depends on the setting in the table
argument which accepts the following tags:
Source:
CreateSample()
should fetch the
audio data for the sample. It must be set to a string that identifies
the audio data source. The following sources are possible:
CreateSample()
will then read length
PCM frames from this table. If
length
is not specified, then CreateSample()
will read all PCM frames
from the table.
ID
tag. It is also necessary
to specify the optional length
argument so that CreateSample()
knows
how many frames it should fetch from the specified file.
ID
tag. It is also
necessary to specify the optional length
argument so that CreateSample()
knows
how many frames it should fetch from the specified memory block.
The default value for the Source
tag is PCM
which means fetch the
audio data from an array of PCM samples stored in the same table as
these options.
ID:
File
and Memory
. In that
case, you need to pass a valid file / memory block identifier here.
Offset:
Memory
. In that
case, it specifies an offset into the memory block at which CreateSample()
should start fetching audio data. The offset is specified in bytes.
Swap:
File
and Memory
and a sample depth of 16 bits. In that case, the Swap
tag can be used to
specify whether or not CreateSample()
should swap the two bytes making up a
16 bit sample. This is required if the sample data in the file or memory block
is encoded in little endian format (LSB first). CreateSample()
, however, requires
16-bit sample data to be in big endian format (MSB first). So if your source can
only provide sample data in LSB format, simply set the Swap
tag to True
and
everything should be fine. This tag defaults to False
which means do not swap
anything.
Please note that the new sample should use at least 1000 PCM frames. If you use less frames, the playback in loop mode will become very CPU intensive. Even if your sample has only 32 different wave forms, you should concatenate them until your sample has at least 1000 frames for performance reasons.
If you pass large sample tables to this function, please do not forget to set these tables to Nil when you no longer need them. Otherwise you will waste great amounts of memory.
Starting with Hollywood 5.0, CreateSample()
can also create empty samples
if you pass an empty table or specify a length of zero. In that case, you
can use functions like InsertSample() to fill the sample with audio data
later.
#MONO8
) (V5.0)Nil
is passed in the first argumentsmpdata = {} slen = 32 For k = 0 To 30 For i = 0 To (slen\2)-1 smpdata[k*slen+i] = -128 smpdata[k*slen+i+(slen\2)] = 127 Next Next CreateSample(1, smpdata, 6982) PlaySample(1)The code above creates a simple beep sound.