APTR handle = hw_LockSample(lua_ID *id, int readonly, struct hwTagList *
                  tags, struct hwos_LockSampleStruct *smplock);

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.

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.

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

handle

handle to the locked sample or NULL on error