hw_LockSample -- gain access to the raw PCM data of a sample (V5.0)
APTR handle = hw_LockSample(lua_ID *id, int readonly, struct hwTagList *
                  tags, struct hwos_LockSampleStruct *smplock);
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:

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

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

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

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

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

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

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

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

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.

Designer compatibility

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

Show TOC