XIMPA SDK - C INTERFACE




Ximpa SDK Package Description

The Ximpa SDK for Windows is delivered as a dynamic link library, other forms are available on request. The SDK defines and implements the Ximpa Sample Rate Converter object and its Application Programming Interface (API). API definitions in C and C++ programming languages are provided. API Wrappers that allow the same dynamic link library to be used from other programming languages can be easily derived. This document describes the C interface, the C++ interface is described here.

The Ximpa object (struct) saves the object state, while the API define the interface between the user application and the services provided by the Ximpa component. An application that wishes to use the Ximpa services first creates and initializes a Ximpa object. The initialization step sets the sample rate conversion parameters, such as input and output sample rates. Once the object is initialized, the application can start processing the input stream of samples. Processing is done by first reading a new buffer of input samples into the Ximpa object's public member inBuf. The application then calls the XimpaConvert() function to process the new buffer and write the converted samples to the Ximpa object's public member outBuf. The converted samples can now be consumed by the application, for instance written to a file. After processing all samples, the application should call the XimpaClean() function to free the internal Ximpa object memory allocated during the initialization process. The object should never be used after the call to XimpaClean().

Ximpa is a multi-channel sample rate converter that can process audio streams of up to 32 channels. Ximpa accepts buffers of interleaved samples and produces buffers in the same format. The samples in an interleaved stereo (two channels) audio stream are arranged as [L0 R0 L1 R1 L2 R2 ...], where L0 is the first left-channel sample and R0 is the first right-channel sample. Li and Ri together are referred to as the ith frame. Ximpa works only with frames not samples. An input buffer passed to XimpaConvert() that contains N frames actually contains N * nChannel samples, where nChannel is the number of the audio stream channels.

Ximpa SDK Package Contents

The SDK contains the following components.

  • "ximpac.h" C declaration file.
  • "ximpac.dll" run-time dynamic link library
  • "ximpac.lib" for use with Microsoft Visual C++ linker.
  • "test_ximpac.c" an application source code written in C showing how to use Ximpa API from the C programming language.
  • Ximpa SDK API documentation.
  • A few audio samples.

Ximpa Object Definition

Ximpa object is defined in C as a struct with the following members. Detailed description of each member and the C API functions is given in the following sections. 

typedef struct _ximpa
{
   int   nChannel;   /* number of channels              */
   void  *src;       /* sample rate converter           */
   int   inBufLen;   /* input buffer length in frames   */
   float *inBuf;     /* input buffer pointer            */
   int   outBufLen;  /* output buffer length in frames  */
   float *outBuf;    /* output buffer pointer           */
   int   inFs;       /* input sampling frequency        */
   int   outFs;      /* output sampling frequency       */
} Ximpa;

Ximpa Public Members

The Ximpa Sample Rate Converter object has a few public member variables. Those variables are documented in this section.

  • inBufLen : Maximum number of frames in the input buffer. This variable is user defined and is passed as an input parameter to the XimpaInit() function.
  • inBuf : Pointer to the buffer holding the input samples to be converted. This buffer is dynamically allocated by the XimpaInit() function. The allocated length is enough to hold inBufLen input frames. The application must fill this buffer with audio samples before calling XimpaConvert().
  • outBufLen : Maximum number of frames in the output buffer. This variable is set by the XimpaInit() function and depends on the input and output sampling rates and the user supplied value of inBufLen.
  • outBuf :Pointer to the buffer holding the converted (processed) samples. This buffer is dynamically allocated by the XimpaInit() function. The allocated length is enough to hold outBufLen output frames. The application must consume the samples in this buffer after each call to XimpaConvert().
  • inFs : Input sampling rate in samples per second. This variable is provided as input to the XimpaInit() function.
  • outFs : Required output sampling rate in samples per second. This variable is provided as input to the XimpaInit() function.

Ximpa Error Codes

Most Ximpa API functions return error codes on failure. The application may translate the returned error code to a user friendly error message by calling XimpaGetErrText() to present the error to the application user. In many cases however, the application developer may wish to take a specific action if a specific error code is returned. In such cases, a knowledge of the error codes and their meaning is necessary. For this purpose, the error codes returned by Ximpa API functions are summarized below.

Error CodeError Number Condition
XIMPA_ERROR_NOERROR0 No Error
XIMPA_ERROR_NULLPOINTER-1 A NULL pointer has been encountered
XIMPA_ERROR_RANGE-2 One or more input parameter is out of its valid range
XIMPA_ERROR_NOMEMORY-3Memory allocation error
XIMPA_ERROR_INTERN-4Ximpa internal error
XIMPA_ERROR_LICENSE-5License error

Ximpa SDK Application Programming Interface

API Summary

Back to API Summary

    int XimpaInit(Ximpa *x, int in_fs, int out_fs, int nCh, int in_buf_len, int fir_len)
  • Initializes a Ximpa sample rate converter object, designs the internal resampling digital filter, and allocates its input and output buffers.
  • Returns :
    • On success returns the actual number of filter coefficients. On failure, returns an error code.
  • Input Parameters :
    • x : the Ximpa object to be initialized.
    • in_fs : input stream sampling rate, must be > 0.
    • out_fs : required output stream sampling rate, must be > 0.
    • nCh : number of channels in the input audio stream (number of samples per frame), must be > 0.
    • in_buf_len : maximum number of frames in the input buffer, must be > 1.
    • fir_len : digital filter length, must be > 1.
  • Error Conditions
    • XIMPA_ERROR_NOMEMORY : Problems allocating memory.
    • XIMPA_ERROR_RANGE : One of the input parameters is out of its valid range.
    • XIMPA_ERROR_INTERN : Ximpa internal error.
    • XIMPA_ERROR_LICENSE : License problem.

Back to API Summary

    int XimpaInitDefault(Ximpa *x, int in_fs, int out_fs, int nCh, int in_buf_len)

  • Initializes a Ximpa sample rate converter object, designs the internal resampling digital filter using the default filter length, and allocates its input and output buffers.
  • Returns :
    • On success returns the actual number of filter coefficients. On failure, returns an error code.
  • Input Parameters :
    • x : the Ximpa object to be initialized.
    • in_fs : input stream sampling rate, must be > 0.
    • out_fs : required output stream sampling rate, must be > 0.
    • nCh : number of channels in the input audio stream (number of samples per frame), must be > 0.
    • in_buf_len : maximum number of frames in the input buffer, must be > 1.
  • Error Conditions
    • XIMPA_ERROR_NOMEMORY : Problems allocating memory.
    • XIMPA_ERROR_RANGE : One of the input parameters is out of its valid range.
    • XIMPA_ERROR_INTERN : Ximpa internal error.
    • XIMPA_ERROR_LICENSE : License problem.

Back to API Summary

    int XimpaConvert(Ximpa *x, int Length)
  • Processes Length input frames from the inBuf and stores the output in outBuf.
  • Returns :
    • On success returns the number of output frames, otherwise an error code.
  • Input Parameters :
    • x : the Ximpa object holding the samples to be processed.
    • Length : number of frames to be processed from the input buffer, must be in the range 1 <= Length <= inBufLen.
  • Error Conditions
    • XIMPA_ERROR_NULLPOINTER : inBuf or outBuf is a NULL pointer.

Back to API Summary

    int XimpaClean(Ximpa *x)
  • Frees the memory allocated by XimpaInit() and puts the Ximpa object in a pre-defined initial state.
  • Returns :
    • Error code.
  • Input Parameters :
    • x : the Ximpa object to be cleaned.
  • Error Conditions
    • XIMPA_ERROR_NOERROR : Returned successfully.

Back to API Summary

    XimpaVersion XimpaGetVersion()
  • Retrieves the Ximpa SDK version number.
  • Returns :
    • XimpaVersion structure defined as follows.
      • typedef struct _ximpaVersion
{
   unsigned char Major;
   unsigned char Minor;
   unsigned char Patch;
   unsigned char Intern;
} XimpaVersion;
  • Input Parameters :
    • void.
  • Error Conditions
    • None.

Back to API Summary

    char* XimpaGetErrText(int errNr)
  • Translates an error number to a user friendly error message.
  • Returns :
    • pointer to a static character string containing a friendly error message corresponding to the input error number. There is no need to allocate or delete memory for the character array.
  • Input Parameters :
    • errNr : Error number to be translated to a text message.
  • Error Conditions
    • None.

Back to API Summary

    char* XimpaGetLicense()
  • Retrieves the license number.
  • Returns :
    • License number.
  • Input Parameters :
    • void.
  • Error Conditions
    • None.

Back to API Summary