xma2defs.h

/***************************************************************************
 *
 * Copyright (c) Microsoft Corporation.  All rights reserved.
 *
 * File:     xma2defs.h
 * Content:  Constants, data types and functions for XMA2 compressed audio.
 *
 ***************************************************************************/

#ifndef __XMA2DEFS_INCLUDED__
#define __XMA2DEFS_INCLUDED__

#include <sal.h>        // Markers for documenting API semantics
#include <winerror.h>   // For S_OK, E_FAIL
#include <audiodefs.h>  // Basic data types and constants for audio work


/***************************************************************************
 *  Overview
 ***************************************************************************/

// A typical XMA2 file contains these RIFF chunks:
//
// 'fmt' or 'XMA2' chunk (or both): A description of the XMA data's structure
// and characteristics (length, channels, sample rate, loops, block size, etc).
//
// 'seek' chunk: A seek table to help navigate the XMA data.
//
// 'data' chunk: The encoded XMA2 data.
//
// The encoded XMA2 data is structured as a set of BLOCKS, which contain PACKETS,
// which contain FRAMES, which contain SUBFRAMES (roughly speaking).  The frames
// in a file may also be divided into several subsets, called STREAMS.
//
// FRAME: A variable-sized segment of XMA data that decodes to exactly 512 mono
//      or stereo PCM samples.  This is the smallest unit of XMA data that can
//      be decoded in isolation.  Frames are an arbitrary number of bits in
//      length, and need not be byte-aligned.  See "XMA frame structure" below.
//
// SUBFRAME: A region of bits in an XMA frame that decodes to 128 mono or stereo
//      samples.  The XMA decoder cannot decode a subframe in isolation; it needs
//      a whole frame to work with.  However, it can begin emitting the frame's
//      decoded samples at any one of the four subframe boundaries.  Subframes
//      can be addressed for seeking and looping purposes.
//
// PACKET: A 2Kb region containing a 32-bit header and some XMA frames.  Frames
//      can (and usually do) span packets.  A packet's header includes the offset
//      in bits of the first frame that begins within that packet.  All of the
//      frames that begin in a given packet belong to the same "stream" (see the
//      Multichannel Audio section below).
//
// STREAM: A set of packets within an XMA file that all contain data for the
//      same mono or stereo component of a PCM file with more than two channels.
//      The packets comprising a given stream may be interleaved with each other
//      more or less arbitrarily; see Multichannel Audio.
//
// BLOCK: An array of XMA packets; or, to break it down differently, a series of
//      consecutive XMA frames, padded at the end with reserved data.  A block
//      must contain at least one 2Kb packet per stream, and it can hold up to
//      4095 packets (8190Kb), but its size is typically in the 32Kb-128Kb range.
//      (The size chosen involves a trade-off between memory use and efficiency
//      of reading from permanent storage.)
//
//      XMA frames do not span blocks, so a block is guaranteed to begin with a
//      set of complete frames, one per stream.  Also, a block in a multi-stream
//      XMA2 file always contains the same number of samples for each stream;
//      see Multichannel Audio.
//
// The 'data' chunk in an XMA2 file is an array of XMA2WAVEFORMAT.BlockCount XMA
// blocks, all the same size (as specified in XMA2WAVEFORMAT.BlockSizeInBytes)
// except for the last one, which may be shorter.


// MULTICHANNEL AUDIO: the XMA decoder can only decode raw XMA data into either
// mono or stereo PCM data.  In order to encode a 6-channel file (say), the file
// must be deinterleaved into 3 stereo streams that are encoded independently,
// producing 3 encoded XMA data streams.  Then the packets in these 3 streams
// are interleaved to produce a single XMA2 file, and some information is added
// to the file so that the original 6-channel audio can be reconstructed at
// decode time.  This works using the concept of an XMA stream (see above).
//
// The frames for all the streams in an XMA file are interleaved in an arbitrary
// order.  To locate a frame that belongs to a given stream in a given XMA block,
// you must examine the first few packets in the block.  Here (and only here) the
// packets are guaranteed to be presented in stream order, so that all frames
// beginning in packet 0 belong to stream 0 (the first stereo pair), etc.
//
// (This means that when decoding multi-stream XMA files, only entire XMA blocks
// should be submitted to the decoder; otherwise it cannot know which frames
// belong to which stream.)
//
// Once you have one frame that belongs to a given stream, you can find the next
// one by looking at the frame's 'NextFrameOffsetBits' value (which is stored in
// its first 15 bits; see XMAFRAME below).  The GetXmaFrameBitPosition function
// uses this technique.


// SEEKING IN XMA2 FILES: Here is some pseudocode to find the byte position and
// subframe in an XMA2 file which will contain sample S when decoded.
//
// 1. Traverse the seek table to find the XMA2 block containing sample S. The
//    seek table is an array of big-endian DWORDs, one per block in the file.
//    The Nth DWORD is the total number of PCM samples that would be obtained
//    by decoding the entire XMA file up to the end of block N.  Hence, the
//    block we want is the first one whose seek table entry is greater than S.
//    (See the GetXmaBlockContainingSample helper function.)
//
// 2. Calculate which frame F within the block found above contains sample S.
//    Since each frame decodes to 512 samples, this is straightforward.  The
//    first frame in the block produces samples X to X + 512, where X is the
//    seek table entry for the prior block.  So F is (S - X) / 512.
//
// 3. Find the bit offset within the block where frame F starts.  Since frames
//    are variable-sized, this can only be done by traversing all the frames in
//    the block until we reach frame F.  (See GetXmaFrameBitPosition.)
//
// 4. Frame F has four 128-sample subframes.  To find the subframe containing S,
//    we can use the formula (S % 512) / 128.
//
// In the case of multi-stream XMA files, sample S is a multichannel sample with
// parts coming from several frames, one per stream.  To find all these frames,
// steps 2-4 need to be repeated for each stream N, using the knowledge that the
// first packets in a block are presented in stream order.  The frame traversal
// in step 3 must be started at the first frame in the Nth packet of the block,
// which will be the first frame for stream N.  (And the packet header will tell
// you the first frame's start position within the packet.)
//
// Step 1 can be performed using the GetXmaBlockContainingSample function below,
// and steps 2-4 by calling GetXmaDecodePositionForSample once for each stream.



/***************************************************************************
 *  XMA constants
 ***************************************************************************/

// Size of the PCM samples produced by the XMA decoder
#define XMA_OUTPUT_SAMPLE_BYTES         2u
#define XMA_OUTPUT_SAMPLE_BITS          (XMA_OUTPUT_SAMPLE_BYTES * 8u)

// Size of an XMA packet
#define XMA_BYTES_PER_PACKET            2048u
#define XMA_BITS_PER_PACKET             (XMA_BYTES_PER_PACKET * 8u)

// Size of an XMA packet header
#define XMA_PACKET_HEADER_BYTES         4u
#define XMA_PACKET_HEADER_BITS          (XMA_PACKET_HEADER_BYTES * 8u)

// Sample blocks in a decoded XMA frame
#define XMA_SAMPLES_PER_FRAME           512u

// Sample blocks in a decoded XMA subframe
#define XMA_SAMPLES_PER_SUBFRAME        128u

// Maximum encoded data that can be submitted to the XMA decoder at a time
#define XMA_READBUFFER_MAX_PACKETS      4095u
#define XMA_READBUFFER_MAX_BYTES        (XMA_READBUFFER_MAX_PACKETS * XMA_BYTES_PER_PACKET)

// Maximum size allowed for the XMA decoder's output buffers
#define XMA_WRITEBUFFER_MAX_BYTES       (31u * 256u)

// Required byte alignment of the XMA decoder's output buffers
#define XMA_WRITEBUFFER_BYTE_ALIGNMENT  256u

// Decode chunk sizes for the XMA_PLAYBACK_INIT.subframesToDecode field
#define XMA_MIN_SUBFRAMES_TO_DECODE     1u
#define XMA_MAX_SUBFRAMES_TO_DECODE     8u
#define XMA_OPTIMAL_SUBFRAMES_TO_DECODE 4u

// LoopCount<255 means finite repetitions; LoopCount=255 means infinite looping
#define XMA_MAX_LOOPCOUNT               254u
#define XMA_INFINITE_LOOP               255u



/***************************************************************************
 *  XMA format structures
 ***************************************************************************/

// The currently recommended way to express format information for XMA2 files
// is the XMA2WAVEFORMATEX structure.  This structure is fully compliant with
// the WAVEFORMATEX standard and contains all the information needed to parse
// and manage XMA2 files in a compact way.

#define WAVE_FORMAT_XMA2 0x166

typedef struct XMA2WAVEFORMATEX
{
    WAVEFORMATEX wfx;
    // Meaning of the WAVEFORMATEX fields here:
    //    wFormatTag;        // Audio format type; always WAVE_FORMAT_XMA2
    //    nChannels;         // Channel count of the decoded audio
    //    nSamplesPerSec;    // Sample rate of the decoded audio
    //    nAvgBytesPerSec;   // Used internally by the XMA encoder
    //    nBlockAlign;       // Decoded sample size; channels * wBitsPerSample / 8
    //    wBitsPerSample;    // Bits per decoded mono sample; always 16 for XMA
    //    cbSize;            // Size in bytes of the rest of this structure (34)

    WORD  NumStreams;        // Number of audio streams (1 or 2 channels each)
    DWORD ChannelMask;       // Spatial positions of the channels in this file,
                             // stored as SPEAKER_xxx values (see audiodefs.h)
    DWORD SamplesEncoded;    // Total number of PCM samples the file decodes to
    DWORD BytesPerBlock;     // XMA block size (but the last one may be shorter)
    DWORD PlayBegin;         // First valid sample in the decoded audio
    DWORD PlayLength;        // Length of the valid part of the decoded audio
    DWORD LoopBegin;         // Beginning of the loop region in decoded sample terms
    DWORD LoopLength;        // Length of the loop region in decoded sample terms
    BYTE  LoopCount;         // Number of loop repetitions; 255 = infinite
    BYTE  EncoderVersion;    // Version of XMA encoder that generated the file
    WORD  BlockCount;        // XMA blocks in file (and entries in its seek table)
} XMA2WAVEFORMATEX, *PXMA2WAVEFORMATEX;


// The legacy XMA format structures are described here for reference, but they
// should not be used in new content.  XMAWAVEFORMAT was the structure used in
// XMA version 1 files.  XMA2WAVEFORMAT was used in early XMA2 files; it is not
// placed in the usual 'fmt' RIFF chunk but in its own 'XMA2' chunk.

#ifndef WAVE_FORMAT_XMA
#define WAVE_FORMAT_XMA 0x0165

// Values used in the ChannelMask fields below.  Similar to the SPEAKER_xxx
// values defined in audiodefs.h, but modified to fit in a single byte.
#ifndef XMA_SPEAKER_LEFT
    #define XMA_SPEAKER_LEFT            0x01
    #define XMA_SPEAKER_RIGHT           0x02
    #define XMA_SPEAKER_CENTER          0x04
    #define XMA_SPEAKER_LFE             0x08
    #define XMA_SPEAKER_LEFT_SURROUND   0x10
    #define XMA_SPEAKER_RIGHT_SURROUND  0x20
    #define XMA_SPEAKER_LEFT_BACK       0x40
    #define XMA_SPEAKER_RIGHT_BACK      0x80
#endif


// Used in XMAWAVEFORMAT for per-stream data
typedef struct XMASTREAMFORMAT
{
    DWORD PsuedoBytesPerSec; // Used by the XMA encoder (typo preserved for legacy reasons)
    DWORD SampleRate;        // The stream's decoded sample rate (in XMA2 files,
                             // this is the same for all streams in the file).
    DWORD LoopStart;         // Bit offset of the frame containing the loop start
                             // point, relative to the beginning of the stream.
    DWORD LoopEnd;           // Bit offset of the frame containing the loop end.
    BYTE  SubframeData;      // Two 4-bit numbers specifying the exact location of
                             // the loop points within the frames that contain them.
                             //   SubframeEnd: Subframe of the loop end frame where
                             //                the loop ends.  Ranges from 0 to 3.
                             //   SubframeSkip: Subframes to skip in the start frame to
                             //                 reach the loop.  Ranges from 0 to 4.
    BYTE  Channels;          // Number of channels in the stream (1 or 2)
    WORD  ChannelMask;       // Spatial positions of the channels in the stream
} XMASTREAMFORMAT;

// Legacy XMA1 format structure
typedef struct XMAWAVEFORMAT
{
    WORD FormatTag;          // Audio format type (always WAVE_FORMAT_XMA)
    WORD BitsPerSample;      // Bit depth (currently required to be 16)
    WORD EncodeOptions;      // Options for XMA encoder/decoder
    WORD LargestSkip;        // Largest skip used in interleaving streams
    WORD NumStreams;         // Number of interleaved audio streams
    BYTE LoopCount;          // Number of loop repetitions; 255 = infinite
    BYTE Version;            // XMA encoder version that generated the file.
                             // Always 3 or higher for XMA2 files.
    XMASTREAMFORMAT XmaStreams[1]; // Per-stream format information; the actual
                                   // array length is in the NumStreams field.
} XMAWAVEFORMAT;


// Used in XMA2WAVEFORMAT for per-stream data
typedef struct XMA2STREAMFORMAT
{
    BYTE Channels;           // Number of channels in the stream (1 or 2)
    BYTE RESERVED;           // Reserved for future use
    WORD ChannelMask;        // Spatial positions of the channels in the stream
} XMA2STREAMFORMAT;

// Legacy XMA2 format structure (big-endian byte ordering)
typedef struct XMA2WAVEFORMAT
{
    BYTE  Version;           // XMA encoder version that generated the file.
                             // Always 3 or higher for XMA2 files.
    BYTE  NumStreams;        // Number of interleaved audio streams
    BYTE  RESERVED;          // Reserved for future use
    BYTE  LoopCount;         // Number of loop repetitions; 255 = infinite
    DWORD LoopBegin;         // Loop begin point, in samples
    DWORD LoopEnd;           // Loop end point, in samples
    DWORD SampleRate;        // The file's decoded sample rate
    DWORD EncodeOptions;     // Options for the XMA encoder/decoder
    DWORD PsuedoBytesPerSec; // Used internally by the XMA encoder
    DWORD BlockSizeInBytes;  // Size in bytes of this file's XMA blocks (except
                             // possibly the last one).  Always a multiple of
                             // 2Kb, since XMA blocks are arrays of 2Kb packets.
    DWORD SamplesEncoded;    // Total number of PCM samples encoded in this file
    DWORD SamplesInSource;   // Actual number of PCM samples in the source
                             // material used to generate this file
    DWORD BlockCount;        // Number of XMA blocks in this file (and hence
                             // also the number of entries in its seek table)
    XMA2STREAMFORMAT Streams[1]; // Per-stream format information; the actual
                                 // array length is in the NumStreams field.
} XMA2WAVEFORMAT;

#endif // #ifndef WAVE_FORMAT_XMA



/***************************************************************************
 *  XMA packet structure (in big-endian form)
 ***************************************************************************/

typedef struct XMA2PACKET
{
    int FrameCount        :  6;  // Number of XMA frames that begin in this packet
    int FrameOffsetInBits : 15;  // Bit of XmaData where the first complete frame begins
    int PacketMetaData    :  3;  // Metadata stored in the packet (always 1 for XMA2)
    int PacketSkipCount   :  8;  // How many packets belonging to other streams must be
                                 // skipped to find the next packet belonging to this one
    BYTE XmaData[XMA_BYTES_PER_PACKET - sizeof(DWORD)];  // XMA encoded data
} XMA2PACKET;

// E.g. if the first DWORD of a packet is 0x30107902:
//
// 001100 000001000001111 001 00000010
//    |          |         |      |____ Skip 2 packets to find the next one for this stream
//    |          |         |___________ XMA2 signature (always 001)
//    |          |_____________________ First frame starts 527 bits into packet
//    |________________________________ Packet contains 12 frames


// Helper functions to extract the fields above from an XMA packet.  (Note that
// the bitfields cannot be read directly on little-endian architectures such as
// the Intel x86, as they are laid out in big-endian form.)

__inline DWORD GetXmaPacketFrameCount(__in_bcount(1) const BYTE* pPacket)
{
    return (DWORD)(pPacket[0] >> 2);
}

__inline DWORD GetXmaPacketFirstFrameOffsetInBits(__in_bcount(3) const BYTE* pPacket)
{
    return ((DWORD)(pPacket[0] & 0x3) << 13) |
           ((DWORD)(pPacket[1]) << 5) |
           ((DWORD)(pPacket[2]) >> 3);
}

__inline DWORD GetXmaPacketMetadata(__in_bcount(3) const BYTE* pPacket)
{
    return (DWORD)(pPacket[2] & 0x7);
}

__inline DWORD GetXmaPacketSkipCount(__in_bcount(4) const BYTE* pPacket)
{
    return (DWORD)(pPacket[3]);
}



/***************************************************************************
 *  XMA frame structure
 ***************************************************************************/

// There is no way to represent the XMA frame as a C struct, since it is a
// variable-sized string of bits that need not be stored at a byte-aligned
// position in memory.  This is the layout:
//
// XMAFRAME
// {
//    LengthInBits: A 15-bit number representing the length of this frame.
//    XmaData: Encoded XMA data; its size in bits is (LengthInBits - 15).
// }

// Size in bits of the frame's initial LengthInBits field
#define XMA_BITS_IN_FRAME_LENGTH_FIELD 15

// Special LengthInBits value that marks an invalid final frame
#define XMA_FINAL_FRAME_MARKER 0x7FFF



/***************************************************************************
 *  XMA helper functions
 ***************************************************************************/

// We define a local ASSERT macro to equal the global one if it exists.
// You can define XMA2DEFS_ASSERT in advance to override this default.
#ifndef XMA2DEFS_ASSERT
    #ifdef ASSERT
        #define XMA2DEFS_ASSERT ASSERT
    #else
        #define XMA2DEFS_ASSERT(a) /* No-op by default */
    #endif
#endif


// GetXmaBlockContainingSample: Use a given seek table to find the XMA block
// containing a given decoded sample.  Note that the seek table entries in an
// XMA file are stored in big-endian form and may need to be converted prior
// to calling this function.

__inline HRESULT GetXmaBlockContainingSample
(
    DWORD nBlockCount,                      // Blocks in the file (= seek table entries)
    __in_ecount(nBlockCount) const DWORD* pSeekTable,  // Pointer to the seek table data
    DWORD nDesiredSample,                   // Decoded sample to locate
    __out DWORD* pnBlockContainingSample,   // Index of the block containing the sample
    __out DWORD* pnSampleOffsetWithinBlock  // Position of the sample in this block
)
{
    DWORD nPreviousTotalSamples = 0;
    DWORD nBlock;
    DWORD nTotalSamplesSoFar;

    XMA2DEFS_ASSERT(pSeekTable);
    XMA2DEFS_ASSERT(pnBlockContainingSample);
    XMA2DEFS_ASSERT(pnSampleOffsetWithinBlock);

    for (nBlock = 0; nBlock < nBlockCount; ++nBlock)
    {
        nTotalSamplesSoFar = pSeekTable[nBlock];
        if (nTotalSamplesSoFar > nDesiredSample)
        {
            *pnBlockContainingSample = nBlock;
            *pnSampleOffsetWithinBlock = nDesiredSample - nPreviousTotalSamples;
            return S_OK;
        }
        nPreviousTotalSamples = nTotalSamplesSoFar;
    }

    return E_FAIL;
}


// GetXmaFrameLengthInBits: Reads a given frame's LengthInBits field.

__inline DWORD GetXmaFrameLengthInBits
(
    __in_bcount(nBitPosition / 8 + 3)
    __in const BYTE* pPacket,  // Pointer to XMA packet[s] containing the frame
    DWORD nBitPosition         // Bit offset of the frame within this packet
)
{
    DWORD nRegion;
    DWORD nBytePosition = nBitPosition / 8;
    DWORD nBitOffset = nBitPosition % 8;

    if (nBitOffset < 2) // Only need to read 2 bytes (and might not be safe to read more)
    {
        nRegion = (DWORD)(pPacket[nBytePosition+0]) << 8 |
                  (DWORD)(pPacket[nBytePosition+1]);
        return (nRegion >> (1 - nBitOffset)) & 0x7FFF;  // Last 15 bits
    }
    else // Need to read 3 bytes
    {
        nRegion = (DWORD)(pPacket[nBytePosition+0]) << 16 |
                  (DWORD)(pPacket[nBytePosition+1]) << 8 |
                  (DWORD)(pPacket[nBytePosition+2]);
        return (nRegion >> (9 - nBitOffset)) & 0x7FFF;  // Last 15 bits
    }
}


// GetXmaFrameBitPosition: Calculates the bit offset of a given frame within
// an XMA block or set of blocks.  Returns 0 on failure.

__inline DWORD GetXmaFrameBitPosition
(
    __in_bcount(nXmaDataBytes) const BYTE* pXmaData,  // Pointer to XMA block[s]
    DWORD nXmaDataBytes,                              // Size of pXmaData in bytes
    DWORD nStreamIndex,                               // Stream within which to seek
    DWORD nDesiredFrame                               // Frame sought
)
{
    const BYTE* pCurrentPacket;
    DWORD nPacketsExamined = 0;
    DWORD nFrameCountSoFar = 0;
    DWORD nFramesToSkip;
    DWORD nFrameBitOffset;

    XMA2DEFS_ASSERT(pXmaData);
    XMA2DEFS_ASSERT(nXmaDataBytes % XMA_BYTES_PER_PACKET == 0);

    // Get the first XMA packet belonging to the desired stream, relying on the
    // fact that the first packets for each stream are in consecutive order at
    // the beginning of an XMA block.

    pCurrentPacket = pXmaData + nStreamIndex * XMA_BYTES_PER_PACKET;
    for (;;)
    {
        // If we have exceeded the size of the XMA data, return failure
        if (pCurrentPacket + XMA_BYTES_PER_PACKET > pXmaData + nXmaDataBytes)
        {
            return 0;
        }

        // If the current packet contains the frame we are looking for...
        if (nFrameCountSoFar + GetXmaPacketFrameCount(pCurrentPacket) > nDesiredFrame)
        {
            // See how many frames in this packet we need to skip to get to it
            XMA2DEFS_ASSERT(nDesiredFrame >= nFrameCountSoFar);
            nFramesToSkip = nDesiredFrame - nFrameCountSoFar;

            // Get the bit offset of the first frame in this packet
            nFrameBitOffset = XMA_PACKET_HEADER_BITS + GetXmaPacketFirstFrameOffsetInBits(pCurrentPacket);

            // Advance nFrameBitOffset to the frame of interest
            while (nFramesToSkip--)
            {
                nFrameBitOffset += GetXmaFrameLengthInBits(pCurrentPacket, nFrameBitOffset);
            }

            // The bit offset to return is the number of bits from pXmaData to
            // pCurrentPacket plus the bit offset of the frame of interest
            return (DWORD)(pCurrentPacket - pXmaData) * 8 + nFrameBitOffset;
        }

        // If we haven't found the right packet yet, advance our counters
        ++nPacketsExamined;
        nFrameCountSoFar += GetXmaPacketFrameCount(pCurrentPacket);

        // And skip to the next packet belonging to the same stream
        pCurrentPacket += XMA_BYTES_PER_PACKET * (GetXmaPacketSkipCount(pCurrentPacket) + 1);
    }
}


// GetLastXmaFrameBitPosition: Calculates the bit offset of the last complete
// frame in an XMA block or set of blocks.

__inline DWORD GetLastXmaFrameBitPosition
(
    __in_bcount(nXmaDataBytes) const BYTE* pXmaData,  // Pointer to XMA block[s]
    DWORD nXmaDataBytes,                              // Size of pXmaData in bytes
    DWORD nStreamIndex                                // Stream within which to seek
)
{
    const BYTE* pLastPacket;
    DWORD nBytesToNextPacket;
    DWORD nFrameBitOffset;
    DWORD nFramesInLastPacket;

    XMA2DEFS_ASSERT(pXmaData);
    XMA2DEFS_ASSERT(nXmaDataBytes % XMA_BYTES_PER_PACKET == 0);
    XMA2DEFS_ASSERT(nXmaDataBytes >= XMA_BYTES_PER_PACKET * (nStreamIndex + 1));

    // Get the first XMA packet belonging to the desired stream, relying on the
    // fact that the first packets for each stream are in consecutive order at
    // the beginning of an XMA block.
    pLastPacket = pXmaData + nStreamIndex * XMA_BYTES_PER_PACKET;

    // Search for the last packet belonging to the desired stream
    for (;;)
    {
        nBytesToNextPacket = XMA_BYTES_PER_PACKET * (GetXmaPacketSkipCount(pLastPacket) + 1);
        XMA2DEFS_ASSERT(nBytesToNextPacket);
        if (pLastPacket + nBytesToNextPacket + XMA_BYTES_PER_PACKET > pXmaData + nXmaDataBytes)
        {
            break;  // The next packet would extend beyond the end of pXmaData
        }
        pLastPacket += nBytesToNextPacket;
    }

    // The last packet can sometimes have no seekable frames, in which case we
    // have to use the previous one
    if (GetXmaPacketFrameCount(pLastPacket) == 0)
    {
        pLastPacket -= nBytesToNextPacket;
    }

    // Found the last packet.  Get the bit offset of its first frame.
    nFrameBitOffset = XMA_PACKET_HEADER_BITS + GetXmaPacketFirstFrameOffsetInBits(pLastPacket);

    // Traverse frames until we reach the last one
    nFramesInLastPacket = GetXmaPacketFrameCount(pLastPacket);
    while (--nFramesInLastPacket)
    {
        nFrameBitOffset += GetXmaFrameLengthInBits(pLastPacket, nFrameBitOffset);
    }

    // The bit offset to return is the number of bits from pXmaData to
    // pLastPacket plus the offset of the last frame in this packet.
    return (DWORD)(pLastPacket - pXmaData) * 8 + nFrameBitOffset;
}


// GetXmaDecodePositionForSample: Obtains the information needed to make the
// decoder generate audio starting at a given sample position relative to the
// beginning of the given XMA block: the bit offset of the appropriate frame,
// and the right subframe within that frame.  This data can be passed directly
// to the XMAPlaybackSetDecodePosition function.

__inline HRESULT GetXmaDecodePositionForSample
(
    __in_bcount(nXmaDataBytes) const BYTE* pXmaData,  // Pointer to XMA block[s]
    DWORD nXmaDataBytes,                              // Size of pXmaData in bytes
    DWORD nStreamIndex,                               // Stream within which to seek
    DWORD nDesiredSample,                             // Sample sought
    __out DWORD* pnBitOffset,                         // Returns the bit offset within pXmaData of
                                                      // the frame containing the sample sought
    __out DWORD* pnSubFrame                           // Returns the subframe containing the sample
)
{
    DWORD nDesiredFrame = nDesiredSample / XMA_SAMPLES_PER_FRAME;
    DWORD nSubFrame = (nDesiredSample % XMA_SAMPLES_PER_FRAME) / XMA_SAMPLES_PER_SUBFRAME;
    DWORD nBitOffset = GetXmaFrameBitPosition(pXmaData, nXmaDataBytes, nStreamIndex, nDesiredFrame);

    XMA2DEFS_ASSERT(pnBitOffset);
    XMA2DEFS_ASSERT(pnSubFrame);

    if (nBitOffset)
    {
        *pnBitOffset = nBitOffset;
        *pnSubFrame = nSubFrame;
        return S_OK;
    }
    else
    {
        return E_FAIL;
    }
}


// GetXmaSampleRate: Obtains the legal XMA sample rate (24, 32, 44.1 or 48Khz)
// corresponding to a generic sample rate.

__inline DWORD GetXmaSampleRate(DWORD dwGeneralRate)
{
    DWORD dwXmaRate = 48000; // Default XMA rate for all rates above 44100Hz

    if (dwGeneralRate <= 24000)      dwXmaRate = 24000;
    else if (dwGeneralRate <= 32000) dwXmaRate = 32000;
    else if (dwGeneralRate <= 44100) dwXmaRate = 44100;

    return dwXmaRate;
}


// Functions to convert between WAVEFORMATEXTENSIBLE channel masks (combinations
// of the SPEAKER_xxx flags defined in audiodefs.h) and XMA channel masks (which
// are limited to eight possible speaker positions: left, right, center, low
// frequency, side left, side right, back left and back right).

__inline DWORD GetStandardChannelMaskFromXmaMask(BYTE bXmaMask)
{
    DWORD dwStandardMask = 0;

    if (bXmaMask & XMA_SPEAKER_LEFT)           dwStandardMask |= SPEAKER_FRONT_LEFT;
    if (bXmaMask & XMA_SPEAKER_RIGHT)          dwStandardMask |= SPEAKER_FRONT_RIGHT;
    if (bXmaMask & XMA_SPEAKER_CENTER)         dwStandardMask |= SPEAKER_FRONT_CENTER;
    if (bXmaMask & XMA_SPEAKER_LFE)            dwStandardMask |= SPEAKER_LOW_FREQUENCY;
    if (bXmaMask & XMA_SPEAKER_LEFT_SURROUND)  dwStandardMask |= SPEAKER_SIDE_LEFT;
    if (bXmaMask & XMA_SPEAKER_RIGHT_SURROUND) dwStandardMask |= SPEAKER_SIDE_RIGHT;
    if (bXmaMask & XMA_SPEAKER_LEFT_BACK)      dwStandardMask |= SPEAKER_BACK_LEFT;
    if (bXmaMask & XMA_SPEAKER_RIGHT_BACK)     dwStandardMask |= SPEAKER_BACK_RIGHT;

    return dwStandardMask;
}

__inline BYTE GetXmaChannelMaskFromStandardMask(DWORD dwStandardMask)
{
    BYTE bXmaMask = 0;

    if (dwStandardMask & SPEAKER_FRONT_LEFT)    bXmaMask |= XMA_SPEAKER_LEFT;
    if (dwStandardMask & SPEAKER_FRONT_RIGHT)   bXmaMask |= XMA_SPEAKER_RIGHT;
    if (dwStandardMask & SPEAKER_FRONT_CENTER)  bXmaMask |= XMA_SPEAKER_CENTER;
    if (dwStandardMask & SPEAKER_LOW_FREQUENCY) bXmaMask |= XMA_SPEAKER_LFE;
    if (dwStandardMask & SPEAKER_SIDE_LEFT)     bXmaMask |= XMA_SPEAKER_LEFT_SURROUND;
    if (dwStandardMask & SPEAKER_SIDE_RIGHT)    bXmaMask |= XMA_SPEAKER_RIGHT_SURROUND;
    if (dwStandardMask & SPEAKER_BACK_LEFT)     bXmaMask |= XMA_SPEAKER_LEFT_BACK;
    if (dwStandardMask & SPEAKER_BACK_RIGHT)    bXmaMask |= XMA_SPEAKER_RIGHT_BACK;

    return bXmaMask;
}


// LocalizeXma2Format: Modifies a XMA2WAVEFORMATEX structure in place to comply
// with the current platform's byte-ordering rules (little- or big-endian).

__inline HRESULT LocalizeXma2Format(__inout XMA2WAVEFORMATEX* pXma2Format)
{
    #define XMASWAP2BYTES(n) ((WORD)(((n) >> 8) | (((n) & 0xff) << 8)))
    #define XMASWAP4BYTES(n) ((DWORD)((n) >> 24 | (n) << 24 | ((n) & 0xff00) << 8 | ((n) & 0xff0000) >> 8))

    if (pXma2Format->wfx.wFormatTag == WAVE_FORMAT_XMA2)
    {
        return S_OK;
    }
    else if (XMASWAP2BYTES(pXma2Format->wfx.wFormatTag) == WAVE_FORMAT_XMA2)
    {
        pXma2Format->wfx.wFormatTag      = XMASWAP2BYTES(pXma2Format->wfx.wFormatTag);
        pXma2Format->wfx.nChannels       = XMASWAP2BYTES(pXma2Format->wfx.nChannels);
        pXma2Format->wfx.nSamplesPerSec  = XMASWAP4BYTES(pXma2Format->wfx.nSamplesPerSec);
        pXma2Format->wfx.nAvgBytesPerSec = XMASWAP4BYTES(pXma2Format->wfx.nAvgBytesPerSec);
        pXma2Format->wfx.nBlockAlign     = XMASWAP2BYTES(pXma2Format->wfx.nBlockAlign);
        pXma2Format->wfx.wBitsPerSample  = XMASWAP2BYTES(pXma2Format->wfx.wBitsPerSample);
        pXma2Format->wfx.cbSize          = XMASWAP2BYTES(pXma2Format->wfx.cbSize);
        pXma2Format->NumStreams          = XMASWAP2BYTES(pXma2Format->NumStreams);
        pXma2Format->ChannelMask         = XMASWAP4BYTES(pXma2Format->ChannelMask);
        pXma2Format->SamplesEncoded      = XMASWAP4BYTES(pXma2Format->SamplesEncoded);
        pXma2Format->BytesPerBlock       = XMASWAP4BYTES(pXma2Format->BytesPerBlock);
        pXma2Format->PlayBegin           = XMASWAP4BYTES(pXma2Format->PlayBegin);
        pXma2Format->PlayLength          = XMASWAP4BYTES(pXma2Format->PlayLength);
        pXma2Format->LoopBegin           = XMASWAP4BYTES(pXma2Format->LoopBegin);
        pXma2Format->LoopLength          = XMASWAP4BYTES(pXma2Format->LoopLength);
        pXma2Format->BlockCount          = XMASWAP2BYTES(pXma2Format->BlockCount);
        return S_OK;
    }
    else
    {
        return E_FAIL; // Not a recognizable XMA2 format
    }

    #undef XMASWAP2BYTES
    #undef XMASWAP4BYTES
}


#endif // #ifndef __XMA2DEFS_INCLUDED__