Subversion Repositories Games.Chess Giants

Rev

Blame | Last modification | View Log | Download | RSS feed

  1. /*-========================================================================-_
  2.  |                                 - XAPO -                                 |
  3.  |        Copyright (c) Microsoft Corporation.  All rights reserved.        |
  4.  |~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~|
  5.  |PROJECT: XAPO                         MODEL:   Unmanaged User-mode        |
  6.  |VERSION: 1.0                          EXCEPT:  No Exceptions              |
  7.  |CLASS:   N / A                        MINREQ:  WinXP, Xbox360             |
  8.  |BASE:    N / A                        DIALECT: MSC++ 14.00                |
  9.  |>------------------------------------------------------------------------<|
  10.  | DUTY: Cross-platform Audio Processing Object interfaces                  |
  11.  ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
  12.   NOTES:
  13.     1.  Definition of terms:
  14.             DSP: Digital Signal Processing.
  15.  
  16.             CBR: Constant BitRate -- DSP that consumes a constant number of
  17.                  input samples to produce an output sample.
  18.                  For example, a 22kHz to 44kHz resampler is CBR DSP.
  19.                  Even though the number of input to output samples differ,
  20.                  the ratio between input to output rate remains constant.
  21.                  All user-defined XAPOs are assumed to be CBR as
  22.                  XAudio2 only allows CBR DSP to be added to an effect chain.
  23.  
  24.             XAPO: Cross-platform Audio Processing Object --
  25.                   a thin wrapper that manages DSP code, allowing it
  26.                   to be easily plugged into an XAudio2 effect chain.
  27.  
  28.             Frame: A block of samples, one per channel,
  29.                    to be played simultaneously.
  30.  
  31.             In-Place: Processing such that the input buffer equals the
  32.                       output buffer (i.e. input data modified directly).
  33.                       This form of processing is generally more efficient
  34.                       than using separate memory for input and output.
  35.                       However, an XAPO may not perform format conversion
  36.                       when processing in-place.
  37.  
  38.     2.  XAPO member variables are divided into three classifications:
  39.             Immutable: Set once via IXAPO::Initialize and remain
  40.                        constant during the lifespan of the XAPO.
  41.  
  42.             Locked: May change before the XAPO is locked via
  43.                     IXAPO::LockForProcess but remain constant
  44.                     until IXAPO::UnlockForProcess is called.
  45.  
  46.             Dynamic: May change from one processing pass to the next,
  47.                      usually via IXAPOParameters::SetParameters.
  48.                      XAPOs should assign reasonable defaults to their dynamic
  49.                      variables during IXAPO::Initialize/LockForProcess so
  50.                      that calling IXAPOParameters::SetParameters is not
  51.                      required before processing begins.
  52.  
  53.         When implementing an XAPO, determine the type of each variable and
  54.         initialize them in the appropriate method.  Immutable variables are
  55.         generally preferable over locked which are preferable over dynamic.
  56.         That is, one should strive to minimize XAPO state changes for
  57.         best performance, maintainability, and ease of use.
  58.  
  59.     3.  To minimize glitches, the realtime audio processing thread must
  60.         not block.  XAPO methods called by the realtime thread are commented
  61.         as non-blocking and therefore should not use blocking synchronization,
  62.         allocate memory, access the disk, etc.  The XAPO interfaces were
  63.         designed to allow an effect implementer to move such operations
  64.         into other methods called on an application controlled thread.
  65.  
  66.     4.  Extending functionality is accomplished through the addition of new
  67.         COM interfaces.  For example, if a new member is added to a parameter
  68.         structure, a new interface using the new structure should be added,
  69.         leaving the original interface unchanged.
  70.         This ensures consistent communication between future versions of
  71.         XAudio2 and various versions of XAPOs that may exist in an application.
  72.  
  73.     5.  All audio data is interleaved in XAudio2.
  74.         The default audio format for an effect chain is WAVE_FORMAT_IEEE_FLOAT.
  75.  
  76.     6.  User-defined XAPOs should assume all input and output buffers are
  77.         16-byte aligned.
  78.  
  79.     7.  See XAPOBase.h for an XAPO base class which provides a default
  80.         implementation for most of the interface methods defined below.     */
  81.  
  82. #pragma once
  83. //--------------<D-E-F-I-N-I-T-I-O-N-S>-------------------------------------//
  84. #include "comdecl.h" // for DEFINE_IID
  85.  
  86. // XAPO interface IDs
  87. DEFINE_IID(IXAPO,           A90BC001, E897, E897, 55, E4, 9E, 47, 00, 00, 00, 00);
  88. DEFINE_IID(IXAPOParameters, A90BC001, E897, E897, 55, E4, 9E, 47, 00, 00, 00, 01);
  89.  
  90.  
  91. #if !defined(GUID_DEFS_ONLY) // ignore rest if only GUID definitions requested
  92.     #if defined(_XBOX)       // general windows and COM declarations
  93.         #include <xtl.h>
  94.         #include <xobjbase.h>
  95.     #else
  96.         #include <windows.h>
  97.         #include <objbase.h>
  98.     #endif
  99.     #include "audiodefs.h"   // for WAVEFORMATEX etc.
  100.  
  101.     // XAPO error codes
  102.     #define FACILITY_XAPO 0x897
  103.     #define XAPO_E_FORMAT_UNSUPPORTED MAKE_HRESULT(SEVERITY_ERROR, FACILITY_XAPO, 0x01) // requested audio format unsupported
  104.  
  105.     // supported number of channels (samples per frame) range
  106.     #define XAPO_MIN_CHANNELS 1
  107.     #define XAPO_MAX_CHANNELS 64
  108.  
  109.     // supported framerate range
  110.     #define XAPO_MIN_FRAMERATE 1000
  111.     #define XAPO_MAX_FRAMERATE 200000
  112.  
  113.     // unicode string length, including terminator, used with XAPO_REGISTRATION_PROPERTIES
  114.     #define XAPO_REGISTRATION_STRING_LENGTH 256
  115.  
  116.  
  117.     // XAPO property flags, used with XAPO_REGISTRATION_PROPERTIES.Flags:
  118.     // Number of channels of input and output buffers must match,
  119.     // applies to XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS.pFormat.
  120.     #define XAPO_FLAG_CHANNELS_MUST_MATCH      0x00000001
  121.  
  122.     // Framerate of input and output buffers must match,
  123.     // applies to XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS.pFormat.
  124.     #define XAPO_FLAG_FRAMERATE_MUST_MATCH     0x00000002
  125.  
  126.     // Bit depth of input and output buffers must match,
  127.     // applies to XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS.pFormat.
  128.     // Container size of input and output buffers must also match if
  129.     // XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS.pFormat is WAVEFORMATEXTENSIBLE.
  130.     #define XAPO_FLAG_BITSPERSAMPLE_MUST_MATCH 0x00000004
  131.  
  132.     // Number of input and output buffers must match,
  133.     // applies to XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS.
  134.     //
  135.     // Also, XAPO_REGISTRATION_PROPERTIES.MinInputBufferCount must
  136.     // equal XAPO_REGISTRATION_PROPERTIES.MinOutputBufferCount and
  137.     // XAPO_REGISTRATION_PROPERTIES.MaxInputBufferCount must equal
  138.     // XAPO_REGISTRATION_PROPERTIES.MaxOutputBufferCount when used.
  139.     #define XAPO_FLAG_BUFFERCOUNT_MUST_MATCH   0x00000008
  140.  
  141.     // XAPO must be run in-place.  Use this flag only if your DSP
  142.     // implementation cannot process separate input and output buffers.
  143.     // If set, the following flags must also be set:
  144.     //     XAPO_FLAG_CHANNELS_MUST_MATCH
  145.     //     XAPO_FLAG_FRAMERATE_MUST_MATCH
  146.     //     XAPO_FLAG_BITSPERSAMPLE_MUST_MATCH
  147.     //     XAPO_FLAG_BUFFERCOUNT_MUST_MATCH
  148.     //     XAPO_FLAG_INPLACE_SUPPORTED
  149.     //
  150.     // Multiple input and output buffers may be used with in-place XAPOs,
  151.     // though the input buffer count must equal the output buffer count.
  152.     // When multiple input/output buffers are used, the XAPO may assume
  153.     // input buffer [N] equals output buffer [N] for in-place processing.
  154.     #define XAPO_FLAG_INPLACE_REQUIRED         0x00000020
  155.  
  156.     // XAPO may be run in-place.  If the XAPO is used in a chain
  157.     // such that the requirements for XAPO_FLAG_INPLACE_REQUIRED are met,
  158.     // XAudio2 will ensure the XAPO is run in-place.  If not met, XAudio2
  159.     // will still run the XAPO albeit with separate input and output buffers.
  160.     //
  161.     // For example, consider an effect which may be ran in stereo->5.1 mode or
  162.     // mono->mono mode.  When set to stereo->5.1, it will be run with separate
  163.     // input and output buffers as format conversion is not permitted in-place.
  164.     // However, if configured to run mono->mono, the same XAPO can be run
  165.     // in-place.  Thus the same implementation may be conveniently reused
  166.     // for various input/output configurations, while taking advantage of
  167.     // in-place processing when possible.
  168.     #define XAPO_FLAG_INPLACE_SUPPORTED        0x00000010
  169.  
  170.  
  171. //--------------<D-A-T-A---T-Y-P-E-S>---------------------------------------//
  172.     #pragma pack(push, 1) // set packing alignment to ensure consistency across arbitrary build environments
  173.  
  174.  
  175.     // XAPO registration properties, describes general XAPO characteristics, used with IXAPO::GetRegistrationProperties
  176.     typedef struct XAPO_REGISTRATION_PROPERTIES {
  177.         CLSID  clsid;                                          // COM class ID, used with CoCreate
  178.         WCHAR  FriendlyName[XAPO_REGISTRATION_STRING_LENGTH];  // friendly name unicode string
  179.         WCHAR  CopyrightInfo[XAPO_REGISTRATION_STRING_LENGTH]; // copyright information unicode string
  180.         UINT32 MajorVersion;                                   // major version
  181.         UINT32 MinorVersion;                                   // minor version
  182.         UINT32 Flags;                                          // XAPO property flags, describes supported input/output configuration
  183.         UINT32 MinInputBufferCount;                            // minimum number of input buffers required for processing, can be 0
  184.         UINT32 MaxInputBufferCount;                            // maximum number of input buffers supported for processing, must be >= MinInputBufferCount
  185.         UINT32 MinOutputBufferCount;                           // minimum number of output buffers required for processing, can be 0, must match MinInputBufferCount when XAPO_FLAG_BUFFERCOUNT_MUST_MATCH used
  186.         UINT32 MaxOutputBufferCount;                           // maximum number of output buffers supported for processing, must be >= MinOutputBufferCount, must match MaxInputBufferCount when XAPO_FLAG_BUFFERCOUNT_MUST_MATCH used
  187.     } XAPO_REGISTRATION_PROPERTIES;
  188.  
  189.  
  190.     // LockForProcess buffer parameters:
  191.     // Defines buffer parameters that remain constant while an XAPO is locked.
  192.     // Used with IXAPO::LockForProcess.
  193.     //
  194.     // For CBR XAPOs, MaxFrameCount is the only number of frames
  195.     // IXAPO::Process would have to handle for the respective buffer.
  196.     typedef struct XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS {
  197.         const WAVEFORMATEX* pFormat;       // buffer audio format
  198.         UINT32              MaxFrameCount; // maximum number of frames in respective buffer that IXAPO::Process would have to handle, irrespective of dynamic variable settings, can be 0
  199.     } XAPO_LOCKFORPROCESS_PARAMETERS;
  200.  
  201.     // Buffer flags:
  202.     // Describes assumed content of the respective buffer.
  203.     // Used with XAPO_PROCESS_BUFFER_PARAMETERS.BufferFlags.
  204.     //
  205.     // This meta-data can be used by an XAPO to implement
  206.     // optimizations that require knowledge of a buffer's content.
  207.     //
  208.     // For example, XAPOs that always produce silent output from silent input
  209.     // can check the flag on the input buffer to determine if any signal
  210.     // processing is necessary.  If silent, the XAPO may simply set the flag
  211.     // on the output buffer to silent and return, optimizing out the work of
  212.     // processing silent data:  XAPOs that generate silence for any reason may
  213.     // set the buffer's flag accordingly rather than writing out silent
  214.     // frames to the buffer itself.
  215.     //
  216.     // The flags represent what should be assumed is in the respective buffer.
  217.     // The flags may not reflect what is actually stored in memory.
  218.     typedef enum XAPO_BUFFER_FLAGS {
  219.         XAPO_BUFFER_SILENT, // silent data should be assumed, respective memory may be uninitialized
  220.         XAPO_BUFFER_VALID,  // arbitrary data should be assumed (may or may not be silent frames), respective memory initialized
  221.     } XAPO_BUFFER_FLAGS;
  222.  
  223.     // Process buffer parameters:
  224.     // Defines buffer parameters that may change from one
  225.     // processing pass to the next.  Used with IXAPO::Process.
  226.     //
  227.     // Note the byte size of the respective buffer must be at least:
  228.     //      XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS.MaxFrameCount * XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS.pFormat->nBlockAlign
  229.     //
  230.     // Although the audio format and maximum size of the respective
  231.     // buffer is locked (defined by XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS),
  232.     // the actual memory address of the buffer given is permitted to change
  233.     // from one processing pass to the next.
  234.     //
  235.     // For CBR XAPOs, ValidFrameCount is constant while locked and equals
  236.     // the respective XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS.MaxFrameCount.
  237.     typedef struct XAPO_PROCESS_BUFFER_PARAMETERS {
  238.         void*             pBuffer;         // audio data buffer, must be non-NULL
  239.         XAPO_BUFFER_FLAGS BufferFlags;     // describes assumed content of pBuffer, does not affect ValidFrameCount
  240.         UINT32            ValidFrameCount; // number of frames of valid data, must be within respective [0, XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS.MaxFrameCount], always XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS.MaxFrameCount for CBR/user-defined XAPOs, does not affect BufferFlags
  241.     } XAPO_PROCESS_BUFFER_PARAMETERS;
  242.  
  243.  
  244. //--------------<M-A-C-R-O-S>-----------------------------------------------//
  245.     // Memory allocation macros that allow one module to allocate memory and
  246.     // another to free it, by guaranteeing that the same heap manager is used
  247.     // regardless of differences between build environments of the two modules.
  248.     //
  249.     // Used by IXAPO methods that must allocate arbitrary sized structures
  250.     // such as WAVEFORMATEX that are subsequently returned to the application.
  251.     #if defined(_XBOX)
  252.         #define XAPO_ALLOC_ATTRIBUTES MAKE_XALLOC_ATTRIBUTES (      \
  253.             0,                           /* ObjectType */           \
  254.             FALSE,                       /* HeapTracksAttributes */ \
  255.             FALSE,                       /* MustSucceed */          \
  256.             FALSE,                       /* FixedSize */            \
  257.             eXALLOCAllocatorId_XAUDIO2,  /* AllocatorId */          \
  258.             XALLOC_ALIGNMENT_DEFAULT,    /* Alignment */            \
  259.             XALLOC_MEMPROTECT_READWRITE, /* MemoryProtect */        \
  260.             FALSE,                       /* ZeroInitialize */       \
  261.             XALLOC_MEMTYPE_HEAP          /* MemoryType */           \
  262.         )
  263.         #define XAPOAlloc(size) XMemAlloc(size, XAPO_ALLOC_ATTRIBUTES)
  264.         #define XAPOFree(p)     XMemFree(p, XAPO_ALLOC_ATTRIBUTES)
  265.     #else
  266.         #define XAPOAlloc(size) CoTaskMemAlloc(size)
  267.         #define XAPOFree(p)     CoTaskMemFree(p)
  268.     #endif
  269.  
  270.  
  271. //--------------<I-N-T-E-R-F-A-C-E-S>---------------------------------------//
  272.     // IXAPO:
  273.     // The only mandatory XAPO COM interface -- a thin wrapper that manages
  274.     // DSP code, allowing it to be easily plugged into an XAudio2 effect chain.
  275.     #undef INTERFACE
  276.     #define INTERFACE IXAPO
  277.     DECLARE_INTERFACE_(IXAPO, IUnknown) {
  278.           ////
  279.           // DESCRIPTION:
  280.           //  Allocates a copy of the registration properties of the XAPO.
  281.           //
  282.           // PARAMETERS:
  283.           //  ppRegistrationProperties - [out] receives pointer to copy of registration properties, use XAPOFree to free structure, left untouched on failure
  284.           //
  285.           // RETURN VALUE:
  286.           //  COM error code
  287.           ////
  288.         STDMETHOD(GetRegistrationProperties) (THIS_ __deref_out XAPO_REGISTRATION_PROPERTIES** ppRegistrationProperties) PURE;
  289.  
  290.           ////
  291.           // DESCRIPTION:
  292.           //  Queries if an input/output configuration is supported.
  293.           //
  294.           // REMARKS:
  295.           //  This method allows XAPOs to express dependency of input format
  296.           //  with respect to output format.
  297.           //
  298.           //  If the input/output format pair configuration is unsupported,
  299.           //  this method also determines the nearest input format supported.
  300.           //  Nearest meaning closest bit depth, framerate, and channel count,
  301.           //  in that order of importance.
  302.           //
  303.           //  The behaviour of this method should remain constant after the
  304.           //  XAPO has been initialized.
  305.           //
  306.           // PARAMETERS:
  307.           //  pOutputFormat          - [in]  output format known to be supported
  308.           //  pRequestedInputFormat  - [in]  input format to examine
  309.           //  ppSupportedInputFormat - [out] receives pointer to nearest input format supported if not NULL and input/output configuration unsupported, use XAPOFree to free structure, left untouched on any failure except XAPO_E_FORMAT_UNSUPPORTED
  310.           //
  311.           // RETURN VALUE:
  312.           //  COM error code, including:
  313.           //    S_OK                      - input/output configuration supported, ppSupportedInputFormat left untouched
  314.           //    XAPO_E_FORMAT_UNSUPPORTED - input/output configuration unsupported, ppSupportedInputFormat receives pointer to nearest input format supported if not NULL
  315.           //    E_INVALIDARG              - either audio format invalid, ppSupportedInputFormat left untouched
  316.           ////
  317.         STDMETHOD(IsInputFormatSupported) (THIS_ const WAVEFORMATEX* pOutputFormat, const WAVEFORMATEX* pRequestedInputFormat, __deref_opt_out WAVEFORMATEX** ppSupportedInputFormat) PURE;
  318.  
  319.           ////
  320.           // DESCRIPTION:
  321.           //  Queries if an input/output configuration is supported.
  322.           //
  323.           // REMARKS:
  324.           //  This method allows XAPOs to express dependency of output format
  325.           //  with respect to input format.
  326.           //
  327.           //  If the input/output format pair configuration is unsupported,
  328.           //  this method also determines the nearest output format supported.
  329.           //  Nearest meaning closest bit depth, framerate, and channel count,
  330.           //  in that order of importance.
  331.           //
  332.           //  The behaviour of this method should remain constant after the
  333.           //  XAPO has been initialized.
  334.           //
  335.           // PARAMETERS:
  336.           //  pInputFormat            - [in]  input format known to be supported
  337.           //  pRequestedOutputFormat  - [in]  output format to examine
  338.           //  ppSupportedOutputFormat - [out] receives pointer to nearest output format supported if not NULL and input/output configuration unsupported, use XAPOFree to free structure, left untouched on any failure except XAPO_E_FORMAT_UNSUPPORTED
  339.           //
  340.           // RETURN VALUE:
  341.           //  COM error code, including:
  342.           //    S_OK                      - input/output configuration supported, ppSupportedOutputFormat left untouched
  343.           //    XAPO_E_FORMAT_UNSUPPORTED - input/output configuration unsupported, ppSupportedOutputFormat receives pointer to nearest output format supported if not NULL
  344.           //    E_INVALIDARG              - either audio format invalid, ppSupportedOutputFormat left untouched
  345.           ////
  346.         STDMETHOD(IsOutputFormatSupported) (THIS_ const WAVEFORMATEX* pInputFormat, const WAVEFORMATEX* pRequestedOutputFormat, __deref_opt_out WAVEFORMATEX** ppSupportedOutputFormat) PURE;
  347.  
  348.           ////
  349.           // DESCRIPTION:
  350.           //  Performs any effect-specific initialization if required.
  351.           //
  352.           // REMARKS:
  353.           //  The contents of pData are defined by the XAPO.
  354.           //  Immutable variables (constant during the lifespan of the XAPO)
  355.           //  should be set once via this method.
  356.           //  Once initialized, an XAPO cannot be initialized again.
  357.           //
  358.           //  An XAPO should be initialized before passing it to XAudio2
  359.           //  as part of an effect chain.  XAudio2 will not call this method;
  360.           //  it exists for future content-driven initialization by XACT.
  361.           //
  362.           // PARAMETERS:
  363.           //  pData        - [in] effect-specific initialization parameters, may be NULL if DataByteSize == 0
  364.           //  DataByteSize - [in] size of pData in bytes, may be 0 if DataByteSize is NULL
  365.           //
  366.           // RETURN VALUE:
  367.           //  COM error code
  368.           ////
  369.         STDMETHOD(Initialize) (THIS_ __in_bcount_opt(DataByteSize) const void* pData, UINT32 DataByteSize) PURE;
  370.  
  371.           ////
  372.           // DESCRIPTION:
  373.           //  Resets variables dependent on frame history.
  374.           //
  375.           // REMARKS:
  376.           //  All other variables remain unchanged, including variables set by
  377.           //  IXAPOParameters::SetParameters.
  378.           //
  379.           //  For example, an effect with delay should zero out its delay line
  380.           //  during this method, but should not reallocate anything as the
  381.           //  XAPO remains locked with a constant input/output configuration.
  382.           //
  383.           //  XAudio2 calls this method only if the XAPO is locked.
  384.           //  This method should not block as it is called from the
  385.           //  realtime thread.
  386.           //
  387.           // PARAMETERS:
  388.           //  void
  389.           //
  390.           // RETURN VALUE:
  391.           //  void
  392.           ////
  393.         STDMETHOD_(void, Reset) (THIS) PURE;
  394.  
  395.           ////
  396.           // DESCRIPTION:
  397.           //  Locks the XAPO to a specific input/output configuration,
  398.           //  allowing it to do any final initialization before Process
  399.           //  is called on the realtime thread.
  400.           //
  401.           // REMARKS:
  402.           //  Once locked, the input/output configuration and any other locked
  403.           //  variables remain constant until UnlockForProcess is called.
  404.           //
  405.           //  XAPOs should assert the input/output configuration is supported
  406.           //  and that any required effect-specific initialization is complete.
  407.           //  IsInputFormatSupported, IsOutputFormatSupported, and Initialize
  408.           //  should be called as necessary before this method is called.
  409.           //
  410.           //  All internal memory buffers required for Process should be
  411.           //  allocated by the time this method returns successfully
  412.           //  as Process is non-blocking and should not allocate memory.
  413.           //
  414.           //  Once locked, an XAPO cannot be locked again until
  415.           //  UnLockForProcess is called.
  416.           //
  417.           // PARAMETERS:
  418.           //  InputLockedParameterCount  - [in] number of input buffers, must be within [XAPO_REGISTRATION_PROPERTIES.MinInputBufferCount, XAPO_REGISTRATION_PROPERTIES.MaxInputBufferCount]
  419.           //  pInputLockedParameters     - [in] array of input locked buffer parameter structures, may be NULL if InputLockedParameterCount == 0, otherwise must have InputLockedParameterCount elements
  420.           //  OutputLockedParameterCount - [in] number of output buffers, must be within [XAPO_REGISTRATION_PROPERTIES.MinOutputBufferCount, XAPO_REGISTRATION_PROPERTIES.MaxOutputBufferCount], must match InputLockedParameterCount when XAPO_FLAG_BUFFERCOUNT_MUST_MATCH used
  421.           //  pOutputLockedParameters    - [in] array of output locked buffer parameter structures, may be NULL if OutputLockedParameterCount == 0, otherwise must have OutputLockedParameterCount elements
  422.           //
  423.           // RETURN VALUE:
  424.           //  COM error code
  425.           ////
  426.         STDMETHOD(LockForProcess) (THIS_ UINT32 InputLockedParameterCount, __in_ecount_opt(InputLockedParameterCount) const XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS* pInputLockedParameters, UINT32 OutputLockedParameterCount, __in_ecount_opt(OutputLockedParameterCount) const XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS* pOutputLockedParameters) PURE;
  427.  
  428.           ////
  429.           // DESCRIPTION:
  430.           //  Opposite of LockForProcess.  Variables allocated during
  431.           //  LockForProcess should be deallocated by this method.
  432.           //
  433.           // REMARKS:
  434.           //  Unlocking an XAPO allows an XAPO instance to be reused with
  435.           //  different input/output configurations.
  436.           //
  437.           // PARAMETERS:
  438.           //  void
  439.           //
  440.           // RETURN VALUE:
  441.           //  void
  442.           ////
  443.         STDMETHOD_(void, UnlockForProcess) (THIS) PURE;
  444.  
  445.           ////
  446.           // DESCRIPTION:
  447.           //  Runs the XAPO's DSP code on the given input/output buffers.
  448.           //
  449.           // REMARKS:
  450.           //  In addition to writing to the output buffers as appropriate,
  451.           //  an XAPO must set the BufferFlags and ValidFrameCount members
  452.           //  of all elements in pOutputProcessParameters accordingly.
  453.           //
  454.           //  ppInputProcessParameters will not necessarily be the same as
  455.           //  ppOutputProcessParameters for in-place processing, rather
  456.           //  the pBuffer members of each will point to the same memory.
  457.           //
  458.           //  Multiple input/output buffers may be used with in-place XAPOs,
  459.           //  though the input buffer count must equal the output buffer count.
  460.           //  When multiple input/output buffers are used with in-place XAPOs,
  461.           //  the XAPO may assume input buffer [N] equals output buffer [N].
  462.           //
  463.           //  When IsEnabled is FALSE, the XAPO should process thru.
  464.           //  Thru processing means an XAPO should not apply its normal
  465.           //  processing to the given input/output buffers during Process.
  466.           //  It should instead pass data from input to output with as little
  467.           //  modification possible.  Effects that perform format conversion
  468.           //  should continue to do so.  The effect must ensure transitions
  469.           //  between normal and thru processing do not introduce
  470.           //  discontinuities into the signal.
  471.           //
  472.           //  XAudio2 calls this method only if the XAPO is locked.
  473.           //  This method should not block as it is called from the
  474.           //  realtime thread.
  475.           //
  476.           // PARAMETERS:
  477.           //  InputProcessParameterCount  - [in]     number of input buffers, matches respective InputLockedParameterCount parameter given to LockForProcess
  478.           //  pInputProcessParameters     - [in]     array of input process buffer parameter structures, may be NULL if InputProcessParameterCount == 0, otherwise must have InputProcessParameterCount elements
  479.           //  OutputProcessParameterCount - [in]     number of output buffers, matches respective OutputLockedParameterCount parameter given to LockForProcess
  480.           //  pOutputProcessParameters    - [in/out] array of output process buffer parameter structures, may be NULL if OutputProcessParameterCount == 0, otherwise must have OutputProcessParameterCount elements
  481.           //  IsEnabled                   - [in]     TRUE to process normally, FALSE to process thru
  482.           //
  483.           // RETURN VALUE:
  484.           //  void
  485.           ////
  486.         STDMETHOD_(void, Process) (THIS_ UINT32 InputProcessParameterCount, __in_ecount_opt(InputProcessParameterCount) const XAPO_PROCESS_BUFFER_PARAMETERS* pInputProcessParameters, UINT32 OutputProcessParameterCount, __inout_ecount_opt(OutputProcessParameterCount) XAPO_PROCESS_BUFFER_PARAMETERS* pOutputProcessParameters, BOOL IsEnabled) PURE;
  487.  
  488.           ////
  489.           // DESCRIPTION:
  490.           //  Returns the number of input frames required to generate the
  491.           //  requested number of output frames.
  492.           //
  493.           // REMARKS:
  494.           //  XAudio2 may call this method to determine how many input frames
  495.           //  an XAPO requires.  This is constant for locked CBR XAPOs;
  496.           //  this method need only be called once while an XAPO is locked.
  497.           //
  498.           //  XAudio2 calls this method only if the XAPO is locked.
  499.           //  This method should not block as it is called from the
  500.           //  realtime thread.
  501.           //
  502.           // PARAMETERS:
  503.           //  OutputFrameCount - [in] requested number of output frames, must be within respective [0, XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS.MaxFrameCount], always XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS.MaxFrameCount for CBR/user-defined XAPOs
  504.           //
  505.           // RETURN VALUE:
  506.           //  number of input frames required
  507.           ////
  508.         STDMETHOD_(UINT32, CalcInputFrames) (THIS_ UINT32 OutputFrameCount) PURE;
  509.  
  510.           ////
  511.           // DESCRIPTION:
  512.           //  Returns the number of output frames generated for the
  513.           //  requested number of input frames.
  514.           //
  515.           // REMARKS:
  516.           //  XAudio2 may call this method to determine how many output frames
  517.           //  an XAPO will generate.  This is constant for locked CBR XAPOs;
  518.           //  this method need only be called once while an XAPO is locked.
  519.           //
  520.           //  XAudio2 calls this method only if the XAPO is locked.
  521.           //  This method should not block as it is called from the
  522.           //  realtime thread.
  523.           //
  524.           // PARAMETERS:
  525.           //  InputFrameCount - [in] requested number of input frames, must be within respective [0, XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS.MaxFrameCount], always XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS.MaxFrameCount for CBR/user-defined XAPOs
  526.           //
  527.           // RETURN VALUE:
  528.           //  number of output frames generated
  529.           ////
  530.         STDMETHOD_(UINT32, CalcOutputFrames) (THIS_ UINT32 InputFrameCount) PURE;
  531.     };
  532.  
  533.  
  534.  
  535.     // IXAPOParameters:
  536.     // Optional XAPO COM interface that allows an XAPO to use
  537.     // effect-specific parameters.
  538.     #undef INTERFACE
  539.     #define INTERFACE IXAPOParameters
  540.     DECLARE_INTERFACE_(IXAPOParameters, IUnknown) {
  541.           ////
  542.           // DESCRIPTION:
  543.           //  Sets effect-specific parameters.
  544.           //
  545.           // REMARKS:
  546.           //  This method may only be called on the realtime thread;
  547.           //  no synchronization between it and IXAPO::Process is necessary.
  548.           //
  549.           //  This method should not block as it is called from the
  550.           //  realtime thread.
  551.           //
  552.           // PARAMETERS:
  553.           //  pParameters       - [in] effect-specific parameter block, must be != NULL
  554.           //  ParameterByteSize - [in] size of pParameters in bytes, must be > 0
  555.           //
  556.           // RETURN VALUE:
  557.           //  void
  558.           ////
  559.         STDMETHOD_(void, SetParameters) (THIS_ __in_bcount(ParameterByteSize) const void* pParameters, UINT32 ParameterByteSize) PURE;
  560.  
  561.           ////
  562.           // DESCRIPTION:
  563.           //  Gets effect-specific parameters.
  564.           //
  565.           // REMARKS:
  566.           //  Unlike SetParameters, XAudio2 does not call this method on the
  567.           //  realtime thread.  Thus, the XAPO must protect variables shared
  568.           //  with SetParameters/Process using appropriate synchronization.
  569.           //
  570.           // PARAMETERS:
  571.           //  pParameters       - [out] receives effect-specific parameter block, must be != NULL
  572.           //  ParameterByteSize - [in]  size of pParameters in bytes, must be > 0
  573.           //
  574.           // RETURN VALUE:
  575.           //  void
  576.           ////
  577.         STDMETHOD_(void, GetParameters) (THIS_ __out_bcount(ParameterByteSize) void* pParameters, UINT32 ParameterByteSize) PURE;
  578.     };
  579.  
  580.  
  581. //--------------<M-A-C-R-O-S>-----------------------------------------------//
  582.     // macros to allow XAPO interfaces to be used in C code
  583.     #if !defined(__cplusplus)
  584.         // IXAPO
  585.         #define IXAPO_QueryInterface(This, riid, ppInterface) \
  586.             ( (This)->lpVtbl->QueryInterface(This, riid, ppInterface) )
  587.  
  588.         #define IXAPO_AddRef(This) \
  589.             ( (This)->lpVtbl->AddRef(This) )
  590.  
  591.         #define IXAPO_Release(This) \
  592.             ( (This)->lpVtbl->Release(This) )
  593.  
  594.         #define IXAPO_GetRegistrationProperties(This, ppRegistrationProperties) \
  595.             ( (This)->lpVtbl->GetRegistrationProperties(This, ppRegistrationProperties) )
  596.  
  597.         #define IXAPO_IsInputFormatSupported(This, pOutputFormat, pRequestedInputFormat, ppSupportedInputFormat) \
  598.             ( (This)->lpVtbl->IsInputFormatSupported(This, pOutputFormat, pRequestedInputFormat, ppSupportedInputFormat) )
  599.  
  600.         #define IXAPO_IsOutputFormatSupported(This, pInputFormat, pRequestedOutputFormat, ppSupportedOutputFormat) \
  601.             ( (This)->lpVtbl->IsOutputFormatSupported(This, pInputFormat, pRequestedOutputFormat, ppSupportedOutputFormat) )
  602.  
  603.         #define IXAPO_Initialize(This, pData, DataByteSize) \
  604.             ( (This)->lpVtbl->Initialize(This, pData, DataByteSize) )
  605.  
  606.         #define IXAPO_Reset(This) \
  607.             ( (This)->lpVtbl->Reset(This) )
  608.  
  609.         #define IXAPO_LockForProcess(This, InputLockedParameterCount, pInputLockedParameters, OutputLockedParameterCount, pOutputLockedParameters) \
  610.             ( (This)->lpVtbl->LockForProcess(This, InputLockedParameterCount, pInputLockedParameters, OutputLockedParameterCount, pOutputLockedParameters) )
  611.  
  612.         #define IXAPO_UnlockForProcess(This) \
  613.             ( (This)->lpVtbl->UnlockForProcess(This) )
  614.  
  615.         #define IXAPO_Process(This, InputProcessParameterCount, pInputProcessParameters, OutputProcessParameterCount, pOutputProcessParameters, IsEnabled) \
  616.             ( (This)->lpVtbl->Process(This, InputProcessParameterCount, pInputProcessParameters, OutputProcessParameterCount, pOutputProcessParameters, IsEnabled) )
  617.  
  618.         #define IXAPO_CalcInputFrames(This, OutputFrameCount) \
  619.             ( (This)->lpVtbl->CalcInputFrames(This, OutputFrameCount) )
  620.  
  621.         #define IXAPO_CalcOutputFrames(This, InputFrameCount) \
  622.             ( (This)->lpVtbl->CalcOutputFrames(This, InputFrameCount) )
  623.  
  624.  
  625.         // IXAPOParameters
  626.         #define IXAPOParameters_QueryInterface(This, riid, ppInterface) \
  627.             ( (This)->lpVtbl->QueryInterface(This, riid, ppInterface) )
  628.  
  629.         #define IXAPOParameters_AddRef(This) \
  630.             ( (This)->lpVtbl->AddRef(This) )
  631.  
  632.         #define IXAPOParameters_Release(This) \
  633.             ( (This)->lpVtbl->Release(This) )
  634.  
  635.         #define IXAPOParameters_SetParameters(This, pParameters, ParameterByteSize) \
  636.             ( (This)->lpVtbl->SetParameters(This, pParameters, ParameterByteSize) )
  637.  
  638.         #define IXAPOParameters_GetParameters(This, pParameters, ParameterByteSize) \
  639.             ( (This)->lpVtbl->GetParameters(This, pParameters, ParameterByteSize) )
  640.     #endif // !defined(__cplusplus)
  641.  
  642.  
  643.     #pragma pack(pop) // revert packing alignment
  644. #endif // !defined(GUID_DEFS_ONLY)
  645. //---------------------------------<-EOF->----------------------------------//
  646.