home *** CD-ROM | disk | FTP | other *** search
/ C/C++ User's Journal & Wi…eveloper's Journal Tools / C-C__Users_Journal_and_Windows_Developers_Journal_Tools_1997.iso / diamond / c / dws.h next >
Encoding:
C/C++ Source or Header  |  1996-09-21  |  16.2 KB  |  470 lines
  1. /******************************************************************************
  2. File:      dws.h
  3. Version:   1.00
  4. Tab stops: every 2 columns
  5. Project:   DiamondWare's Sound ToolKit for Windows
  6. Copyright: 1994-1996 DiamondWare, Ltd.  All rights reserved.
  7. Written:   95/09/01 by John Lundy (based on dws.h for the dos STK)
  8. Purpose:   Contains declarations for the DW Sound ToolKit for Windows
  9. History:   95/09/01 JCL Started
  10.            96/03/27 KW, EL & JCL finalized for 1.0
  11.            96/04/14 JCL finalized 1.01
  12.            96/05/11 JCL finalized 1.1
  13.            96/05/27 JCL finalized 1.11
  14.            96/09/21 KW finalized for v1.2 (support for IBM Visual Age C++)
  15. ******************************************************************************/
  16.  
  17.  
  18.  
  19. #ifndef dws_INCLUDE
  20.  
  21.   #define dws_INCLUDE
  22.  
  23.  
  24.  
  25.   /* For Powersoft Optima++ */
  26.   #if defined (__WATCOMC__) && !defined (__WINDOWS__)
  27.     typedef unsigned char  BYTE;
  28.     typedef unsigned short WORD;
  29.     typedef unsigned long  DWORD;
  30.     typedef unsigned int   UINT;
  31.   #endif
  32.  
  33.   #if defined(__NT__) && !defined(WIN32)
  34.     #define WIN32
  35.   #endif
  36.  
  37.   #if defined(_WIN32) && !defined(WIN32)
  38.     #define WIN32
  39.   #endif
  40.  
  41.   #if defined(WIN32) && !defined(__BORLANDC__)
  42.     #define DLLEXPORT __declspec(dllexport)
  43.   #else
  44.     #define DLLEXPORT __export
  45.   #endif
  46.  
  47.   #ifndef WIN32
  48.     #if defined(__WATCOMC__) && defined(__WINDOWS_386__)
  49.       #define dws_DIST
  50.     #else
  51.       #define dws_DIST _far
  52.     #endif
  53.   #else
  54.     #define dws_DIST
  55.   #endif
  56.  
  57.   /* For IBM Visual Age for C++ */
  58.   #if defined (__IBMC__) || defined (__IBMCPP__)
  59.     #undef CALLBACK
  60.     #undef DLLEXPORT
  61.     #define CALLBACK
  62.     #define DLLEXPORT _System
  63.   #endif
  64.  
  65.  
  66.  
  67. /*****************************************************************************/
  68.   /*
  69.    . If a call to a dws_ function returns 0 (FALSE), then this is an
  70.    . indication that an error has occured.  Call dws_ErrNo to see which
  71.    . one.  The following series of #defines is the complete list of
  72.    . possible return values for dws_ErrNo.
  73.   */
  74.   #define dws_EZERO                        0  /* no error */
  75.  
  76.   /* The following 8 errors may be triggered by any dws_ function */
  77.   #define dws_NOTINITTED                   1
  78.   #define dws_ALREADYINITTED               2
  79.   #define dws_NOTSUPPORTED                 3
  80.   #define dws_INTERNALERROR                4
  81.   #define dws_INVALIDPOINTER               5
  82.   #define dws_RESOURCEINUSE                6
  83.   #define dws_MEMORYALLOCFAILED            7
  84.   #define dws_SETEVENTFAILED               8
  85.  
  86.   /*
  87.    . dws_BUSY may be triggered during a call to a dws_ function, if any
  88.    . dws_ function is already executing.  Ordinarily, this should never
  89.    . occur.
  90.   */
  91.   #define dws_BUSY                         9
  92.  
  93.   /* This error may be triggered only by dws_Init */
  94.   #define dws_Init_BUFTOOSMALL           101
  95.  
  96.   /* The following 3 errors may be triggered by any dws_D (dig) function */
  97.   #define dws_D_NOTADWD                  201
  98.   #define dws_D_NOTSUPPORTEDVER          202
  99.   #define dws_D_BADDPLAY                 203
  100.  
  101.   /* The following error may be triggered by dws_DPlay */
  102.   #define dws_DPlay_NOSPACEFORSOUND      251
  103.  
  104.   /* These 2 errors may be triggered by dws_WAV2DWD */
  105.   #define dws_WAV2DWD_NOTAWAVE           301
  106.   #define dws_WAV2DWD_UNSUPPORTEDFORMAT  302
  107.  
  108.   /* The following error may be triggered by any dws_M (music) function */
  109.   #define dws_M_BADMPLAY                 401
  110.  
  111.  
  112. /*---------------------------------------------------------------------------*/
  113.   /*
  114.    . This section #defines bitfields which are used by various dws_
  115.    . functions.  Each bit in a bitfield, by definition, may be set/reset
  116.    . independently of all other bits.
  117.   */
  118.  
  119.   /* flags for muscaps value of dws_DETECTRESULTS structure */
  120.   #define dws_muscap_NONE      0x0000 /* no music playback */
  121.   #define dws_muscap_MIDIPORT  0x0001 /* output port */
  122.   #define dws_muscap_SYNTH     0x0002 /* generic int synth */
  123.   #define dws_muscap_SQSYNTH   0x0004 /* square wave int synth */
  124.   #define dws_muscap_FMSYNTH   0x0008 /* FM int synth */
  125.   #define dws_muscap_MAPPER    0x0010 /* MIDI mapper */
  126.   #define dws_muscap_ANY       0x001f /* mask of all available modes */
  127.  
  128.   #define dws_digcap_NONE        0x0000 /* no digitized sound playback */
  129.   #define dws_digcap_11025_08_1  0x0001 /* 11kHz, 8-bit, mono */
  130.   #define dws_digcap_11025_08_2  0x0002 /* 11kHz, 8-bit, stereo */
  131.   #define dws_digcap_11025_16_1  0x0004 /* 11kHz, 16-bit, mono */
  132.   #define dws_digcap_11025_16_2  0x0008 /* 11kHz, 16-bit, stereo */
  133.   #define dws_digcap_22050_08_1  0x0010 /* 22kHz, 8-bit, mono */
  134.   #define dws_digcap_22050_08_2  0x0020 /* 22kHz, 8-bit, stereo */
  135.   #define dws_digcap_22050_16_1  0x0040 /* 22kHz, 16-bit, mono */
  136.   #define dws_digcap_22050_16_2  0x0080 /* 22kHz, 16-bit, stereo */
  137.   #define dws_digcap_44100_08_1  0x0100 /* 44kHz, 8-bit, mono */
  138.   #define dws_digcap_44100_08_2  0x0200 /* 44kHz, 8-bit, stereo */
  139.   #define dws_digcap_44100_16_1  0x0400 /* 44kHz, 16-bit, mono */
  140.   #define dws_digcap_44100_16_2  0x0800 /* 44kHz, 16-bit, stereo */
  141.   #define dws_digcap_ANY         0x0fff /* mask of all available modes */
  142.  
  143.   /*
  144.    . The following #defines are bitfields used in the flags field in the
  145.    . dws_IDEAL struct.
  146.    .
  147.    . SWAPLR should be used to compensate for downstream electronics which
  148.    . switch the left and right field.
  149.    .
  150.    . Since pitch and volume change both require some additional CPU time,
  151.    . you may want to disable them for slow machines and enable for fast
  152.    . machines.  This is an easy way for you to do this, without changing
  153.    . your program around.
  154.    .
  155.    . Notes:
  156.    .   1) Pitch change is slower than volume change.
  157.    .   2) Pitch decrease (dws_DPLAY.pitch > dws_IDENTITY) is slower than
  158.    .      pitch increase
  159.    .   3) When the source sound, or the STK, is 8-bit, raising the volume
  160.    .      is slower than lowering it.  Otherwise both are equal.
  161.   */
  162.   #define dws_ideal_NONE          0x0000  /* this is the normal case */
  163.   #define dws_ideal_SWAPLR        0x0001  /* swap Left & Right on playback */
  164.   #define dws_ideal_DISABLEPITCH  0x0002  /* disable the pitch feature */
  165.   #define dws_ideal_DISABLEVOLUME 0x0004  /* disable the volume feature */
  166.   #define dws_ideal_MAXSPEED      0x0006  /* use this for very slow machines */
  167.  
  168.   /*
  169.    . These are the flag bitfields for the dws_DPLAY structure.
  170.    . Each corresponds to one field in the struct.
  171.   */
  172.   #define dws_dplay_SND         0x00000001L
  173.   #define dws_dplay_COUNT       0x00000002L
  174.   #define dws_dplay_PRIORITY    0x00000004L
  175.   #define dws_dplay_PRESND      0x00000008L
  176.   #define dws_dplay_SOUNDNUM    0x00000010L
  177.   #define dws_dplay_LVOL        0x00000020L
  178.   #define dws_dplay_RVOL        0x00000040L
  179.   #define dws_dplay_PITCH       0x00000080L
  180.   #define dws_dplay_CALLBACK    0x00000100L
  181.   #define dws_dplay_SYNCHRONOUS 0x00000200L
  182.   #define dws_dplay_FIRSTSAMPLE 0x00000400L
  183.   #define dws_dplay_CURSAMPLE   0x00000800L
  184.   #define dws_dplay_LASTSAMPLE  0x00001000L
  185.  
  186.   /* The following 2 consts indicate the status of music playback */
  187.   #define dws_MSONGSTATUSPLAYING  0x0001
  188.   #define dws_MSONGSTATUSPAUSED   0x0002
  189.  
  190.  
  191. /*---------------------------------------------------------------------------*/
  192.   /*
  193.    . When the WIN-STK sends a message to your window, the lParam field
  194.    . indicates the purpose of the message.
  195.   */
  196.   #define dws_event_SOUNDCOMPLETE  0x0001
  197.   #define dws_event_SOUNDSTARTED   0x0002
  198.   #define dws_event_SOUNDABORTED   0x0003
  199.  
  200.  
  201.   /* For no change in volume level or pitch */
  202.   #define dws_IDENTITY 0x100
  203.  
  204.   /* Default priority, if not specified in call to dws_DPlay */
  205.   #define dws_NORMALPRIORITY 0x1000
  206.  
  207.  
  208.  
  209. /*****************************************************************************/
  210.   /* struct member byte alignment - begin */
  211.   #ifdef _MSC_VER
  212.     #ifdef WIN32
  213.       #pragma pack(push, dws_h, 2) /* Use 2 byte alignment for these structs */
  214.     #else
  215.       #pragma pack(2)
  216.     #endif
  217.   #endif
  218.  
  219.   #if defined(__SC__) || defined(__WATCOMC__)
  220.     #pragma pack(push, 2) /* Use 2 byte alignment for these structs */
  221.   #endif
  222.  
  223.  
  224.  
  225.   /*
  226.    . This section declares the struct types used by the STK.  In each
  227.    . case, the user must create an instance of the struct prior to making
  228.    . a call to any STK function which takes a pointer to it.  The STK does
  229.    . not keep a pointer to any of these structs internally; after the call
  230.    . returns, you may deallocate it, if you wish.
  231.    .
  232.    . NB: The STK _does_ keep pointers to digitized sound buffers!
  233.   */
  234.  
  235.   /*
  236.    . A pointer to this struct is passed to dws_DetectHardWare, which fills
  237.    . it in.  It should then be passed to dws_Init.  If you plan on writing
  238.    . this struct out to a file, it's important that you write the entire
  239.    . contents.  There is information (for internal STK use only) in the
  240.    . reserved[] field!
  241.   */
  242.   typedef struct
  243.   {
  244.     /* This field indicates which music capabilities are available, if any */
  245.     DWORD muscaps;      /* see dws_muscap_xxxxxx #defines above */
  246.  
  247.     /* This field indicates which dig capabilities are available, if any */
  248.     DWORD digcaps;      /* see dws_digcap_xxxxxx #defines above */
  249.  
  250.     /* This field should be modified only with caution */
  251.     DWORD digbfr;       /* minimum buffer size */
  252.  
  253.     BYTE  reserved[20];
  254.  
  255.   } dws_DETECTRESULTS;
  256.  
  257.  
  258.   /*
  259.    . A pointer to this struct is passed as a parameter to dws_Init.  This
  260.    . struct allows the program to let the STK know what capabilities it
  261.    . will actually use.
  262.   */
  263.   typedef struct
  264.   {
  265.     DWORD flags;         /* use combination of dws_ideal_xxxx */
  266.     DWORD mustyp;        /* use dws_muscap_xxxxxx (mode) to select */
  267.  
  268.     DWORD digtyp;        /* use dws_digcap_xxxxxx (mode) to select */
  269.     WORD  dignvoices;    /* maximum number of digitized voices you'll use */
  270.  
  271.     BYTE  reserved[18];
  272.  
  273.   } dws_IDEAL;
  274.  
  275.  
  276.   /*
  277.    . A pointer to this struct is passed to dws_DPlay.
  278.    .
  279.    . NB: The soundnum field is filled in by dws_DPlay as a return value.
  280.   */
  281.   typedef struct
  282.   {
  283.     DWORD flags;         /* flag indicates active fields in struct         */
  284.     BYTE  dws_DIST *snd; /* pointer to buffer which holds a .DWD file      */
  285.     WORD  count;         /* number of times to play, or 0=infinite loop    */
  286.     WORD  priority;      /* higher numbers mean higher priority            */
  287.     WORD  presnd;        /* soundnum to sequence sound _after_             */
  288.     WORD  soundnum;      /* dws_DPlay returns a snd number from 10-65535   */
  289.     WORD  lvol;          /* 0-65535, 0 is off, 256 is dws_IDENTITY         */
  290.     WORD  rvol;          /* if the output is mono lvol & rvol are averaged */
  291.     WORD  pitch;         /* 1-65535, 256 is dws_IDENTITY (0 is unuseable)  */
  292.     WORD  dummy;         /* added to insure DWORD alignment                */
  293.     HWND  hwndmsg;       /* handle of window to which to send msg          */
  294.     UINT  message;       /* message sent to window hwndmsg                 */
  295.     DWORD firstsample;   /* first sample of sound buffer for play or loop  */
  296.     DWORD cursample;     /* current sample playing within sound            */
  297.     DWORD lastsample;    /* last sample of sound buffer for play or loop   */
  298.  
  299.     #ifdef WIN32
  300.       BYTE reserved[4];
  301.     #else
  302.       BYTE reserved[8];
  303.     #endif
  304.  
  305.   } dws_DPLAY;
  306.  
  307.  
  308.   /* A pointer to this struct is passed to dws_MPlay. */
  309.   typedef struct
  310.   {
  311.     BYTE dws_DIST *track;   /* ptr to NULL-terminated .MID file name string */
  312.     WORD count;             /* number of times to play, or 0=infinite loop */
  313.  
  314.     BYTE reserved[10];
  315.  
  316.   } dws_MPLAY;
  317.  
  318.  
  319.  
  320.   /* struct member byte alignment - end */
  321.   #ifdef _MSC_VER
  322.     #ifdef  WIN32
  323.       #pragma pack(pop, dws_h) /* back to default packing */
  324.     #else
  325.       #pragma pack()
  326.     #endif
  327.   #endif
  328.  
  329.   #if defined(__SC__) || defined(__WATCOMC__)
  330.     #pragma pack(pop) /* back to default packing */
  331.   #endif
  332.  
  333. /*****************************************************************************/
  334.   /* This section prototypes the WIN-STK functions */
  335.  
  336.   #ifdef __cplusplus
  337.     extern "C" {
  338.   #endif
  339.  
  340.  
  341.  
  342.   /*
  343.    . This function is callable at any time.  It returns the number of the
  344.    . last error which occured.
  345.   */
  346.   WORD DLLEXPORT CALLBACK dws_ErrNo(void);
  347.  
  348. /*---------------------------------------------------------------------------*/
  349.  
  350.  
  351.   /*
  352.    . Each function in this section has a boolean return value.  A 0 (FALSE)
  353.    . indicates that the function failed in some way.  In this case, call
  354.    . dws_ErrNo to get the specific error.  Otherwise, a return value of 1
  355.    . (TRUE) indicates that all is well.
  356.   */
  357.   WORD DLLEXPORT CALLBACK dws_DetectHardWare(dws_DETECTRESULTS dws_DIST *dr);
  358.  
  359.   WORD DLLEXPORT CALLBACK dws_Init(dws_DETECTRESULTS dws_DIST *dr,
  360.                                    dws_IDEAL dws_DIST *ideal);
  361.  
  362.  
  363.   /*
  364.    . If the program has called dws_Init, it _MUST_ call dws_Kill before it
  365.    . terminates.
  366.   */
  367.   WORD DLLEXPORT CALLBACK dws_Kill(void);
  368.  
  369.  
  370.   /*
  371.    . The following function is the digital mixer of the STK.  A
  372.    . value of 0 is off; dws_IDENTITY is normal, and 0xffff is maximum
  373.    . volume (grossly distorted).
  374.   */
  375.   WORD DLLEXPORT CALLBACK dws_XDig(WORD lvolume, WORD rvolume);
  376.  
  377.  
  378.   /*
  379.    . The following 9 functions comprise the digitized sound functions of
  380.    . the STK.  See the documentation for complete details.
  381.   */
  382.   WORD DLLEXPORT CALLBACK dws_DPlay(dws_DPLAY dws_DIST *dplay);
  383.  
  384.   /*
  385.    . Allows you to change the following items:
  386.    .   count
  387.    .   priority
  388.    .   lvol
  389.    .   rvol
  390.    .   pitch
  391.    .   hwndmsg and message (simultaneously)
  392.   */
  393.   WORD DLLEXPORT CALLBACK dws_DSetInfo(dws_DPLAY dws_DIST *dplay1,
  394.                                        dws_DPLAY dws_DIST *dplay2);
  395.  
  396.   /*
  397.    . Takes a ptr to a dws_DPLAY struct; soundnum specifies which sound.
  398.    .
  399.    . Can retrieve the current values for any or all of the following:
  400.    .   snd
  401.    .   count
  402.    .   priority
  403.    .   presnd
  404.    .   lvol
  405.    .   rvol
  406.    .   pitch
  407.    .   hwndmsg and message (simultaneously)
  408.   */
  409.   WORD DLLEXPORT CALLBACK dws_DGetInfo(dws_DPLAY dws_DIST *dplay1,
  410.                                        dws_DPLAY dws_DIST *dplay2);
  411.  
  412.   /* Callable at any time--even before dws_Init or after dws_Kill */
  413.   WORD DLLEXPORT CALLBACK dws_DGetRateFromDWD(BYTE dws_DIST *snd,
  414.                                               WORD dws_DIST *rate);
  415.  
  416.   WORD DLLEXPORT CALLBACK dws_DDiscard(WORD soundnum);
  417.  
  418.   WORD DLLEXPORT CALLBACK dws_DDiscardAO(BYTE dws_DIST *snd);
  419.  
  420.   WORD DLLEXPORT CALLBACK dws_DClear(void);       /* global */
  421.  
  422.   WORD DLLEXPORT CALLBACK dws_DPause(void);       /* global */
  423.  
  424.   WORD DLLEXPORT CALLBACK dws_DUnPause(void);     /* global */
  425.  
  426.   /*
  427.    . Converts a .WAV buffer to a .DWD buffer
  428.    .
  429.    . This function has two usages.  In the first, pass the wave pointer, the
  430.    . wave length in *len and a NULL pointer for dwd.  The routine will return
  431.    . the length of the buffer required to hold the resulting DWD in *len.  In
  432.    . the second usage, allocate a buffer of the correct size and pass its
  433.    . address in dwd.  Make sure you pass the wave pointer in wave and the size
  434.    . of the wave in *len.  It will then perform the conversion, returning the
  435.    . number of bytes used in *len.
  436.   */
  437.   WORD DLLEXPORT CALLBACK dws_WAV2DWD(BYTE dws_DIST *wave, DWORD dws_DIST *len,
  438.                                       BYTE dws_DIST *dwd);
  439.  
  440.   /* The following 5 functions comprise the music functions of the STK. */
  441.   WORD DLLEXPORT CALLBACK dws_MPlay(dws_MPLAY dws_DIST *mplay);
  442.  
  443.   WORD DLLEXPORT CALLBACK dws_MSongStatus(WORD dws_DIST *result);
  444.  
  445.   WORD DLLEXPORT CALLBACK dws_MClear(void);
  446.  
  447.   WORD DLLEXPORT CALLBACK dws_MPause(void);
  448.  
  449.   WORD DLLEXPORT CALLBACK dws_MUnPause(void);
  450.  
  451.   /*
  452.    . If your 16-bit application can't yield CPU time to the system, it must
  453.    . call this function periodically to prevent the sound from pausing.
  454.    . This is not required for 32-bit applications, but the function is
  455.    . supported for compatibility.
  456.   */
  457.   WORD DLLEXPORT CALLBACK dws_Update(void);        /* Affects all sounds */
  458.  
  459.  
  460.  
  461.   #ifdef __cplusplus
  462.     }
  463.   #endif
  464.  
  465. /*****************************************************************************/
  466.  
  467.  
  468.  
  469. #endif
  470.