Name
hw_LockSample -- gain access to the raw PCM data of a sample (V5.0)
Synopsis
APTR handle = hw_LockSample(lua_ID *id, int readonly, struct hwTagList *
                  tags, struct hwos_LockSampleStruct *smplock);
Library
sound

Function
This function locks the specified sample and allows you to access its raw PCM data. You have to pass the object identifier of the sample you want to lock as a lua_ID. See Object identifiers for details.

You also have to pass a pointer to a struct hwos_LockSampleStruct which will be filled with all the information you need by hw_LockSample(). struct hwos_LockSampleStruct looks like this:

 
struct hwos_LockSampleStruct
{
    APTR Buffer;        // [out]
    int BufferSize;     // [out]
    int Samples;        // [out]
    int Channels;       // [out]
    int Bits;           // [out]
    int Frequency;      // [out]
    ULONG Flags;        // [out]
};

hw_LockSample() will write to the structure members as follows:

Buffer:
This will point to a buffer which contains the raw PCM samples.

BufferSize:
This will be set to the total size of the PCM buffer passed in Buffer in bytes.

Samples:
The total number of PCM frames in the sample. Note that this value is specified in PCM frames, not in bytes.

Channels:
The number of channels used by the sample. This will be either 1 (mono) or 2 (stereo).

Bits:
The number of bits per PCM sample. This will be either 8 or 16.

Frequency:
The number of PCM frames that should be played per second. Usually 44100 or 48000.

Flags:
A combination of the following flags describing additional properties of the sample:

HWSNDFLAGS_BIGENDIAN
The PCM samples are stored in big endian format. This flag is only meaningful if the bit resolution is 16.

HWSNDFLAGS_SIGNEDINT
The PCM samples are stored as signed integers. This is typically set.

HWSNDFLAGS_SOFTWARE
This flag will be set if the sample is a software sample. (V11.0)

If you do not want to write to the raw PCM buffer, pass True in the readonly parameter. hw_LockSample() will be faster than as it does not have to update the sample data in the sound card memory.

Do not hold sample locks longer than necessary. In particular, do not return control to the script while holding a sample lock because the script might try to modify the sample then and this will lead to trouble in case the sample is still locked. You should call hw_UnLockSample() as soon as possible.

Designer compatibility
Unsupported

Inputs
id
object identifier of sample to be locked
readonly
True for read-only access, False for read/write access
tags
reserved for future use; pass NULL for now
smplock
pointer to a struct hwos_LockSampleStruct that is to be filled by this function
Results
handle
handle to the locked sample or NULL on error
Show TOC