ssplRequestBuffer

Asks for an available buffer.

Synopsis

SoundBufferNode *ssplRequestBuffer ( SoundSpooler *sspl )

Description

ssplRequestBuffer() returns an available SoundBufferNode from the free queue or NULL if none are available (all are in the active queue). When an available SoundBufferNode is returned, the client can attach sample data to it (by calling ssplSetBufferAddressLength()) and submit it to the active queue (by calling ssplSendBuffer()). This function is automatically done for you by the convenience functions ssplSpoolData() and ssplPlayData().

This function gives you write permission to the returned SoundBufferNode. You have that write permission until the SoundBufferNode is returned to the

SoundSpooler with ssplSendBuffer() or ssplUnrequestBuffer().

Argument

sspl: Pointer to a SoundSpooler structure.

Return Value

Pointer to a SoundBufferNode if one is available, or NULL if no buffers are available.

Implementation

Library call implemented in music.lib V21.

Examples

The following code fragment shows proper use of ssplRequestBuffer(), ssplUnrequestBuffer(), ssplSetBufferAddressLength(), and ssplSendBuffer().

Err sendbuffer (SoundSpooler *sspl)
{
    SoundBufferNode *sbn;
    Err errcode;
        // request a buffer
    if ((sbn = ssplRequestBuffer (sspl)) != NULL) {
            // fill buffer, on failure return unused buffer
            // to free queue
        if ((errcode = fillbuffer (sspl, sbn)) < 0) {
            ssplUnrequestBufffer (sspl, sbn);
            return errcode;
        }
            // on success, send buffer (always moves buffer to
            // either free or active queue - no need to unrequest it)
        if ((errcode = ssplSendBuffer (sspl, sbn)) < 0) return 
errcode;
    }
    return 0;
}
Err fillbuffer (SoundSpooler *sspl, SoundBufferNode *sbn)
{
    void *addr;
    uint32 len;
    // your code here to fill buffer - results in addr, len
    return ssplSetBufferAddressLength (sspl, sbn, addr, len);
}

Notes

Prior to music.lib V24, SoundBufferNodes were actually _removed_ from the free list; all knowledge of them was lost by the sound spooler until they were passed back to ssplSendBuffer() to put them back into one of the SoundSpooler's queues. If lost, ssplDeleteSoundSpooler() would lose memory and be unable t o free some items.

Starting with V24, the sound spooler automatically tracks all sound buffer nodes requested by ssplRequestBuffer() in a "requested" queue. Any buffers that are not submitted or "unrequested", get put back into the free list by ssplReset() and freed by ssplDeleteSoundSpooler().

Associated Files

soundspooler.h, music.lib